doc-front-page: mention that "Changeset Evolution" is a specific concept
It will get it own paragraph soon.
.. Copyright © 2014 Greg Ward <greg@gerg.ca>
==================================
Changeset Evolution with Mercurial
==================================
`evolve`_ is a Mercurial extension for faster and safer mutable history. It
implements the changeset evolution concept for `Mercurial`_.
* It offers a safe and simple way to refine changesets locally and propagate
those changes to other repositories.
* It can automatically detect and handle the complex issues that can arise from
exchanging draft changesets.
* It makes it even possible for multiple developers to rewrite the same part of
the history in a distributed way.
* It fully respects the Phases concept so unsure users will only rewrite parts
of the history that are safe to be changed. Phases have been part of Mercurial
since early 2012.
.. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension
.. _`Mercurial`: https://www.mercurial-scm.org/
Installation and setup
----------------------
We recommend you subscribe to the `evolve-testers`_ mailing list to stay up
to date with the latest news and announcement.
.. _`evolve-testers`: https://www.mercurial-scm.org/mailman/listinfo/evolve-testers
Using pip::
pip install --user hg-evolve
Then add in your `hgrc` config::
[extensions]
evolve=
You can easily edit the `hgrc` of repository using `hg config --local` or your
user configuration `hg config --edit`.
Table of Content
----------------
.. toctree::
:maxdepth: 2
index
user-guide
sharing
concepts
from-mq
Why the ``evolve`` extension
----------------------------
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.
For years, Mercurial has included various commands that allow
history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.
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 hidden.
``evolve`` makes things better by changing the behaviour of most existing
history modification commands so they use a safer mechanism (*changeset
obsolescence*, covered below) rather than the older, less safe *strip*
operation.
``evolve`` is built on infrastructure in core Mercurial:
* *Phases* (starting in Mercurial 2.1) allow you to distinguish
mutable and immutable changesets.
* *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 in Mercurial until you start using ``evolve``.
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 update back to the
bad changeset, fix my mistake, amend the 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 remote 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.
``evolve`` is experimental!
---------------------------
The long-term plan for ``evolve`` is to add it to core Mercurial.
However, it is not yet stable enough for that. In particular:
* The UI is unstable: ``evolve``'s command names and command options
are not completely nailed down yet. They are subject to occasional
backwards-incompatible changes. If you write scripts that use
evolve commands, a future release could break your scripts.
* There are still some corner cases that aren't handled yet. If you
think you have found such a case, please check if it's already
described in the Mercurial bug tracker (https://bz.mercurial-scm.org/).
Bugs in ``evolve`` are files under component "evolution": use
`this query`_ to view open bugs in ``evolve``.
.. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE
Next steps:
-----------
* For a practical guide to using ``evolve`` in a single repository,
see the `user guide`_.
* For more advanced tricks, see `sharing mutable history`_.
* To learn about the concepts underlying ``evolve``, see `concepts`_
(incomplete).
* If you're coming from MQ, see the `MQ migration guide`_ (incomplete).
.. _`user guide`: user-guide.html
.. _`sharing mutable history`: sharing.html
.. _`concepts`: concepts.html
.. _`MQ migration guide`: from-mq.html