Changeset Evolution

Contents

  1. Status
  2. Using Evolution
  3. Overview
    1. Rewriting history
    2. Tracking and sharing rewriting
    3. Automatic detection and resolution arising troubles
  4. Current implementation state
  5. Older materials
  6. Related Developer pages

Changeset Evolution is a set of features to gracefully handle history rework operations.

You can read the documentation or watch the talk at FOSDEM 2013 to learn more. (Slides).

1. Status

{i} While well on the way, the full implementation of the changeset evolution concept is still in progress. Core Mercurial already supports many of the associated features, but for now they are still disabled by default. The current implementation has been usable for multiple years already, and some parts of it are used in production in multiple projects and companies (including the Mercurial project itself, Facebook, Google, etc…).

However, there are still some areas were the current implementation has gaps. This means some use cases or performance issues are not handled as well as they currently are without evolution. Mercurial has been around for a long time and is strongly committed to backward compatibility, and turning evolution on by default nowadays could regress the experience of some of our current users. The feature will be enabled by default at the point where users who do not use or care about the new features added by evolution won't be impacted by it.

2. Using Evolution

Using evolution is safe and no data loss/corruption is to be expected. Once you turn evolution on, all commands from core Mercurial will use it. In addition, one can enable evolution locally and still use an "old" server. You won't "poison" the server (but won't be able to use the new feature with that server).

Testing the concept early is useful for us, core developers. It provides us with data and use cases that we need to iron things out before enabling it by default. This is especially true if you can test evolve in a context that involves client/server/distributed workflows.

Here are the recommended steps to try evolution:

  1. Subscribe to the evolve beta tester mailing list,

  2. Install and use the EvolveExtension

  3. Enjoy changeset evolution

The evolve extensions will take care of enabling all the appropriate features in core and add a small layer with the latest state of the new commands and algorithms. The extension is developed by core Mercurial developers and its code collaborates closely with Mercurial's core internals. It is left outside of core to support older versions of Mercurial (extending the tester base) and gain flexibility when experimenting with new algorithms.

As the implementation is still in progress, some command behavior might change. Subscribe to the evolve beta tester mailing list to make sure you stay aware of new releases and the changes they might introduce.

3. Overview

{i} You can also check the evolve documentation.

3.1. Rewriting history

Mercurial offers multiple commands to rewrite history:

The experimental EvolveExtension adds more commands, which will eventually be moved into core:

All these operations are very safe to use, even for Mercurial rookies. Mercurial will actively prevent you from rewriting parts of history which are not safe to rewrite. Read about the Phases concept for details.

3.2. Tracking and sharing rewriting

Obsolescence markers make it possible to mark changesets that have been deleted or superseded by a new version of the changeset.

Unlike the previous way of handling such changes (which stripped the old changesets from the repository), obsolescence markers can be propagated between repositories. This allows for a safe and simple way of exchanging mutable history and altering it after the fact. Changeset phases are respected, such that only draft and secret changesets can be altered (see hg phases for details).

Obsolescence is tracked using "obsolescence markers", a piece of metadata that tracks which changesets have been made obsolete, potential successors for a given changeset, the moment the changeset was marked as obsolete, and the user who performed the rewriting operation. The markers are stored separately from standard changeset data and can be exchanged without any of the precursor changesets, preventing unnecessary exchange of obsolete data.

The complete set of obsolescence markers describes a history of changeset modifications that is orthogonal to the repository history of file modifications. This changeset history allows for detection and automatic resolution of edge cases arising from multiple users rewriting the same part of history concurrently.

3.3. Automatic detection and resolution arising troubles

Exchanging mutable changesets has inherent issues that we must be prepare to deal with. Most people will never run into them but Mercurial is able to detect and solve them automatically. Please note: there was a renaming of the terms used here; what used to be called "troubled" (encompassing the three kinds of issues below) is now called "unstable". You may still encounter documentation using the old terms, please point it out or contribute an update if you notice any.

There are three kinds of unstable changesets:

  1. In some situations you may have non-obsolete changesets descending from obsolete changesets. Such changesets are said to be "orphaned" (this used to be called 'unstable').

  2. In some other situations you may have successors for changesets which are now immutable. In such case the obsolescence marker does not apply and the unlucky successors are said to be "phase-divergent" (this used to be called 'bumped').

  3. Finally when multiple changesets claim to be the successors of changesets they are said to be "content-divergent" (the old name for this was simply 'divergent').

When Mercurial detect such unstable changesets, it will warn the user and prevent push by default. You can use the hg evolve command to automatically resolve them.

This command is partially implemented in the EvolveExtension.

4. Current implementation state

As of January 2017, the following areas are covered:

And the following areas need improvement: (get on the tester mailing list if you get stuck on one of them)

5. Older materials

CategoryNewFeature CategoryEvolution

ChangesetEvolution (last edited 2022-08-14 21:06:00 by StephenRasku)