New evolve docs, take 2: 1/3: index.rst

Greg Ward greg at gerg.ca
Wed May 28 18:35:46 UTC 2014


.. Copyright © 2014 Greg Ward <greg at gerg.ca>

==================================
Changeset Evolution with Mercurial
==================================

`evolve`_ is an experimental Mercurial extension for safe mutable history.

.. _`evolve`: http://mercurial.selenic.com/wiki/EvolveExtension

Normally with Mercurial (and other sane version control systems), a
changeset is permanent and immutable. You can commit new changesets to
modify the source code, but you cannot modify or remove old
changesets. They are carved in stone for all eternity.

Mutable history changes all that, and ``evolve`` is an implementation
of mutable history with a number of nice properties:

  * changesets that you modify or remove are not lost; they are simply
    marked *obsolete* and eventually become *hidden*

  * you cannot mutate changesets that have been published (this is
    actually a feature of core Mercurial that was added to support
    changeset evolution)

  * you can safely share mutable history with your colleagues

Some of the things you can do with ``evolve`` are:

  * Fix a mistake immediately: "Oops! I just committed a changeset
    with a syntax error -- I'll fix that and amend the changeset so no
    one sees my mistake." (While this is possible using existing
    features of core Mercurial, ``evolve`` makes it safer.)

  * Fix a mistake a little bit later: "Oops! I broke the tests three
    commits back, but only noticed it now -- I'll just back up, fix my
    mistake, amend the bad changeset, and evolve history to update the
    affected changesets."

  * Remove unwanted changes: "I hacked in some debug output two
    commits back; everything is working now, so I'll just prune that
    unwanted changeset before pushing."

  * Share mutable history: say you do most of your programming work
    locally, but need to test on a big development server somewhere
    before you know everything is good. You can use ``evolve`` to
    share mutable history between two computers, pushing finely
    polished changesets to a public repository only after testing on
    the dev server.

Additionally, ``evolve`` makes existing history-editing operations
(like ``rebase``) safer. For starters, Mercurial's "phases" feature
prevents you from rebasing published changesets, which was a common
source of pain in Mercurial pre-2.3 (when phases were first added).
More interestingly, ``evolve`` modifies the behaviour of ``rebase`` so
that rebased changesets are marked *obsolete* rather than removed
entirely from the repository. Finally, ``evolve`` makes it possible
for Alice and Bob to share mutable changesets without losing their
minds.

Next steps:
  * For a practical guide to using ``evolve``, see the `user guide`_.
  * For rocket-science tricks, see `sharing mutable history`_.
  * To learn about the concepts underlying ``evolve``, see `concepts`_.
  * If you're coming from MQ, see the `MQ migration guide`_.

.. _`user guide`: user-guide.html
.. _`concepts`: concepts.html
.. _`sharing mutable history`: sharing.html
.. _`MQ migration guide`: from-mq.html



More information about the Evolve-testers mailing list