Changeset Evolution with Mercurial

evolve is an experimental Mercurial extension for safe mutable history.

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 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 ( Bugs in evolve are files under component “evolution”: use this query to view open bugs in evolve.

Installation and setup

To use evolve, you must:

  1. Clone the evolve repository:

    cd ~/src
    hg clone
  2. Configure the extension, either locally

    hg config --local

    or for all your repositories

    hg config --edit

    Then add


    in the [extensions] section (adding the section if necessary). Use the directory that you actually cloned to, of course.

Next steps: