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

Greg Ward greg at gerg.ca
Fri May 30 16:45:25 UTC 2014


Hi Pierre-Yves --

after mulling over your comments, I've ended up pretty much rewriting
index.rst. I think it's much better, and I *think* it takes all of
your criticims into account. Please see for yourself...

'''
.. 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

With core Mercurial, changesets are permanent and immutable. You can
commit new changesets to modify your source code, but you cannot
modify or remove old changesets—they are carved in stone for all
eternity.

For years, Mercurial has included various extensions that allow
history modification: ``rebase``, ``mq``, ``histedit``, and so forth.
These are useful and popular extensions, and in fact history
modification is one of the big reasons DVCSes (distributed version
control systems) like Mercurial took off.

But there's a catch: until now, Mercurial's various mechanisms for
modifying history have been *unsafe*, in that changesets were
destroyed (“stripped”) rather than simply made invisible.

``evolve`` makes things better in a couple of ways:

  * It changes the behaviour of most existing history modification
    extensions (``rebase``, ``histedit``, etc.) so they use a safer
    mechanism (*changeset obsolescence*, covered below) rather than
    the older, less safe *strip* operation.

  * It provides a new way of modifying history that is roughly
    equivalent to ``mq`` (but much nicer and safer).

It helps to understand that ``evolve`` builds on infrastructure
already in core Mercurial:

  * *Phases* (starting in Mercurial 2.1) allow you to distinguish
    mutable and immutable changesets. We'll cover phases early in the
    user guide, since understanding phases is essential to
    understanding ``evolve``.

  * *Changeset obsolescence* (starting in Mercurial 2.3) is how
    Mercurial knows how history has been modified, specifically when
    one changeset replaces another. In the obsolescence model, a
    changeset is neither removed nor modified, but is instead marked
    *obsolete* and typically replaced by a *successor*. Obsolete
    changesets usually become *hidden* as well. Obsolescence is an
    invisible feature until you start using ``evolve``, so we'll cover
    it in the user guide too.

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 and evolve history before pushing."

  * Share mutable history with yourself: say you do most of your
    programming work locally, but need to test on a big test 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 test server.

  * Share mutable history for code review: you don't want to publish
    unreviewed changesets, but you can't block every commit waiting
    for code review. The solution is to share mutable history with
    your reviewer, amending each changeset until it passes review.

Next steps:
  * For a practical guide to using ``evolve`` in a single repository,
    see the `user guide`_.
  * For mode advanced 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
'''

Greg



More information about the Evolve-testers mailing list