---

title: Changeset Evolution training

author: |

  <span style="text-transform: none;"><small>Boris Feld<br/><a href="https://octobus.net">octobus.net</a></small></span>

---

# Introduction

## Welcome

Hello everyone, and welcome to this Changeset Evolution training. During this session, you will learn how to safely rewrite history with Mercurial and Evolve, and how to collaborate together with your colleagues while rewriting the history at the same time.

This training is designed to last approximately ¾ hours.

You will use this repository during the training: [https://bitbucket.org/octobus/evolve_training_repo](https://bitbucket.org/octobus/evolve_training_repo). Please clone it somewhere relevant.

```bash

$ hg clone https://bitbucket.org/octobus/evolve_training_repo

$ cd evolve_training_repo

```

Copy the provided hgrc to ensure a smooth training experience:

```bash

$ cp hgrc .hg/hgrc

```

This training support will contains commands you are expected to type and launch. These commands will be in the following format:

```

$ COMMAND YOU ARE EXPECTED TO TYPE

output you are expecting to see

```

## Preliminary checks

#### Mercurial version

First let's use the following command to verify which version of Mercurial you are using:

```

$ hg --version

Mercurial Distributed SCM (version 4.4.2)

(see https://mercurial-scm.org for more information)

Copyright (C) 2005-2017 Matt Mackall and others

This is free software; see the source for copying conditions. There is NO

warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

```

You need at least Mercurial version `4.1`. If you don't have a recent enough version, please call your instructor.

In order to activate the Evolve extension, add these lines in your user configuration (using the command `hg config --edit`):

```ini

[extensions]

evolve =

topic =

```

#### Mercurial extensions

Now let's check the version of your extensions. You will need all of these for the training:

```

$ hg --version --verbose

[...]

  evolve       external  7.1.0

  topic        external  0.6.0

  rebase       internal

  histedit     internal

```

# The Basics

<!-- #### What is Changeset Evolution?

With core Mercurial, changesets are permanent and history rewriting has been discouraged for a long time. 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.

However, there's a catch: until now, Mercurial's various mechanisms for

modifying history have been *unsafe* and expensive, in that changesets were

destroyed (“stripped”) rather than simply hidden and still easy to recover.

Changeset Evolution 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 a

    disabled feature in Mercurial until you start using ``evolve``.

 XXX More than just than obsolescence in core ? XXX

 XXX The part below is a bit overselling XXX

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 default

    features of core Mercurial, Changeset Evolution 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.

  * Explore and audit the rewrite history of a changeset. Since Mercurial is

    tracking the edits you make to a changeset, you can look at the history of

    these edits. This is similar to Mercurial tracking the history of file

    edits, but at the changeset level. -->

In this section, we are going to learn how to do basic history rewriting like rewriting a changeset or rebasing.

### Amend

The smallest possible history rewriting is rewriting a changeset description message. We often save and close the editor too early, and/or haven't seen a typo.

It is very easy to fix a changeset description message, so let's do that. First be sure that you are in your clone of the `evolve_training_repo`. then update to the `typo` branch:

```

$ hg update typo

```

Check what the current repository looks like:

~~~raw-file

output/fix-a-bug-base.log

~~~

~~~graphviz-file

graphs/fix-bug-1.dot

~~~

We have a root commit and another based on it. Double-check that you are on the right changeset with the `hg summary` command:

~~~raw-file

output/fix-a-bug-base-summary.log

~~~

The current commit description message seems wrong, `Fx bug`, there is definitely a letter missing. Let's fix this typo with the `hg commit` command.

Usually, the `hg commit` is used to create new commit but we can use the ``--amend`` option to instead modify the current commit (see `hg help commit` for more information):

~~~

$ hg commit --amend --message "Fix bug"

~~~

Let's take a look at the repository now:

~~~raw-file

output/amend-after.log

~~~

~~~graphviz-file

graphs/fix-bug-2.dot

~~~

The logs before and after amending looks pretty similar, we are going to analyze the differences later. Did you catch the differences?

### Rebase

<!-- XXX probably needs a sentence about the merge (Why do you want to avoid it) XXX -->

Let's try to rebase something now. Let's say that you have a branch named `build/linuxsupport-v2` which was started on another branch named `build/v2`. Everything was fine until `build/v2` grew a new commit, and now you want to rebase `build/linuxsupport-v2` on top of `build/v2` to be up-to-date with other the changes:

```

$ hg update build/linuxsupport-v2

```

~~~raw-file

output/rebase-before.log

~~~

~~~graphviz-file

graphs/rebase-before.dot

~~~

<!-- XXX-REVIEW: Explain rebase CLI interface -->

Let's rebase our branch on top of `build/v2` with the `hg rebase` command. The `hg rebase` command have many ways to select commits:

1. Explicitly select them using "--rev".

2. Use "--source" to select a root commit and include all of its descendants.

3. Use "--base" to select a commit; rebase will find ancestors and their descendants which are not also ancestors of the destination.

4. If you do not specify any of "--rev", "source", or "--base", rebase  will use "--base ." as above.

For this first example, we are gonna stays simple and explicitly select the commits we want to rebase with the `--rev` option.

The `hg rebase` command also accepts a destination with the ``--dest`` option. And finally, as we are using named branches, don't forget to use the `--keepbranches` or the rebased commits will be on the wrong branch:

~~~raw-file

output/rebase.log

~~~

Now we have a nice, clean and flat history:

~~~raw-file

output/rebase-after.log

~~~

~~~graphviz-file

graphs/rebase-after.dot

~~~

For more details about how to use the `hg rebase` command, see `hg help rebase`.

### Under the hood

What did happened when we just ran the `hg amend` and `hg rebase` commands? What was done exactly to make the whole process work seamlessly?

Let's go back to our previous amend example.

##### Amend

When we did our amend, the status of the repository was:

~~~raw-file

output/behind-the-hood-amend-before-hash-hidden.log

~~~

~~~graphviz-file

graphs/fix-bug-1.dot

~~~

And after the amend, the repository looked like:

~~~raw-file

output/behind-the-hood-amend-after.log

~~~

~~~graphviz-file

graphs/fix-bug-2.dot

~~~

Do you see what is the difference?

The big difference, apart from the fixed changeset message, is the revision hash and revision number. The `Fix bug` revision changed from `d2eb2ac6a5bd` to `708369dc1bfe`. It means that the fixed changeset is a new one. But where did the old changeset go?

It didn't actually go very far, as it just became **hidden**. When we rewrite a changeset with the Evolve extension, instead of blindly delete it, we create a new changeset and hide the old one, which is still there, and we can even see it with the `--hidden` option available on most Mercurial commands:

~~~raw-file

output/under-the-hood-amend-after-log-hidden.log

~~~

Notice the `x` in the log output which shows that a changeset is hidden.

In addition to hiding the original changeset, we are also storing additional information which is recording the relation between a changeset, the **predecessor** and its **successor**. It basically stores the information that the commit **X** was rewritten into the commit **Y** by the user **U** at the date **D**. This piece of information is stored in something called an **obsolescence marker**. It will be displayed like this:

~~~graphviz-file

graphs/fix-bug-3.dot

~~~

Here the commit **5d48a444aba7** was rewritten into **708369dc1bfe**. Also please notice the difference of style of the commit **5d48a444aba7**, that's because it have been rewritten.

##### Rebase

**Successors** don't need to share anything with their **predecessor**. They could have a different description message, user, date or even parents.

Let's look at our earlier rebase example. The status before the rebase was:

~~~raw-file

output/behind-the-hood-rebase-before-hash-hidden.log

~~~

~~~graphviz-file

graphs/rebase-before.dot

~~~

And after it was:

~~~raw-file

output/behind-the-hood-rebase-after.log

~~~

~~~graphviz-file

graphs/rebase-after.dot

~~~

Did the same thing happen under the hood?

Yes, exactly! The old changesets are still around, and they are just hidden.

~~~raw-file

output/rebase-after-hidden.log

~~~

And we created three **obsolescence markers**, between each rebased commit and its **successor**:

~~~graphviz-file

graphs/rebase-after-hidden.dot

~~~

### Evolution History

Mercurial is designed to track the history of files. Evolution goes beyond, and tracks the history of the history of files. It basically tracks the different versions of your commits.

As it is a new dimension of history, the classical Mercurial commands are not always the best to visualize this new history.

We have seen that we can see the **hidden** changesets with the `--hidden` option on `hg log`:

~~~raw-file

output/under-the-hood-amend-after-log-hidden.log

~~~

To visualize the **obsolescence history** of a particular changeset, we can use the dedicated command `hg obslog`. The option are quite similar to `hg log` (you can read `hg help obslog` for more information):

~~~raw-file

output/under-the-hood-amend-after-obslog.log

~~~

We can even print what changed between the two versions with the `--patch` option:

~~~raw-file

output/under-the-hood-amend-after-obslog-patch.log

~~~

Obslog works both ways, as it can display **predecessors** and **successors** with the `--all` option:

```raw-file

output/under-the-hood-amend-after-obslog-no-all.log

```

~~~raw-file

output/under-the-hood-amend-after-obslog-all.log

~~~

~~~graphviz-file

graphs/fix-bug-3.dot

~~~

We can also use obslog on the changesets that we rebased earlier:

~~~raw-file

output/under-the-hood-rebase-after-obslog.log

~~~

Why the `hg obslog` command is only showing two commits while we rebased three of them?

```raw-file

output/under-the-hood-rebase-after-obslog-branch.log

```

And why the `hg obslog` command show disconnected graphs when asking for the obslog of the whole branch?

~~~graphviz-file

graphs/rebase-after-hidden.dot

~~~

While these two obsolescence logs look very similar —because they show a similar change—, the two changesets log histories looked quite different.

Using the `hg log` command to understand the Evolution history is hard because it is designed for displaying the files history, not the Evolution history. The `hg obslog` has been specially designed for this use-case and is more suited for this use-case.

#### TortoiseHG

TortoiseHG should be able to display obsolescence history for your repositories.

To display all the **hidden** commits, we need to click on the **search icon**, then on the **Show/Hide hidden changesets** at the right of the **filter** check box. It is also possible to provide a *revset* to filter the repository, for example `:6 + ::20` to display only the revisions we have been working with until now:

![](img/thg-obs.png)

<!-- #### Deroulement

Travail chacun de son côté pour apprendre à utiliser:

- Réecriture de changeset

- Affichage de l'obsolescence, log, obslog

- Vérifier que chacun sait utiliser les commandes de base

- Vérifier que chacun sait utiliser les commandes de visu, hg log, hg log -G, thg?

=> Pas trop longtemps // répartir

- Créer un commit

- Le amend sans evolve == bundle

- Strip?

- rebase sans evolve?

- Why is it bad? exemple

(Peut-etre pas leur faire pratiquer amend sans evolve, ca prends du temps)

- With evolve, now

- Activate it, check version

- Amend with evolve

- rebase with evolve

- What happened?

- View obs-history, hg log, obslog -->

# Medium level

## More rewriting commands

The `hg amend` and `hg rebase` commands are the foundations for changeset evolution in Mercurial. You could do everything with these, but, luckily for us, the evolve extension provides human-friendly commands for common needs. We are going to see them now:

### Amend

The Evolve extension provides its own `hg amend` command, which is similar to the `hg commit --amend` that we used previously, and adds several nice features:

- The `-e`/`--edit` option edits the commit message in an editor, which is not opened by default any more.

- The user and date can be updated to the current ones with the `-U`/`--current-user` and `-D`/`--current-date` options.

- More capabilities for rewriting the changeset.

The `hg amend` command accepts either file paths, to add all the modifications on these files in the current changeset, or the `-i`/`--interactive` option to select precisely what to add in it.

We are going to use it to rewrite the author of the changeset:

```

$ hg update amend-extract

```

We have two commits on the **amend-extract** branch:

```raw-file

output/amend-extract-before.log

```

The user for the **amend-extract** head seems wrong, so let's fix it with the `hg amend` command:

```raw-file

output/amend-user.log

```

Now let's check that the user has been amended correctly:

```raw-file

output/amend-user-after-export.log

```

The user is the good one, but the diff looks weird. It seems that both a bad file **and** an incorrect line have slipped in this commit. We need to fix that.

There are several solutions here, and we could manually edit the file and amend it. But, luckily for us, the `hg amend` command also has a very helpful option named `--extract` that will help us.

### Amend extract

The `hg amend` command is meant to move file modifications from your working directory to the current changeset (which is considered as the parent of working directory). `hg amend` also provides the option `--extract` that can be used to invert the meaning of the command: with this option, `hg amend` will move the file modifications from your current changeset to your working directory.

This is often used to remove a file or a line that is not meant to be in the current commit.

As usual, we can either pass file paths or use the `-i` option to select which lines to extract.

First, let's extract the badfile:

```raw-file

output/amend-extract-badfile.log

```

Now let's check the status of the changeset and the working directory:

```raw-file

output/amend-extract-badfile-after-export.log

```

The file is not included in the commit anymore! Did it just vanish? What if you wanted to keep it and, for example, put it in another commit?

Don't worry, the extracted files and lines still are in your working directory:

```raw-file

output/amend-extract-badfile-after-status.log

```

As we are not going to need this file anymore, let's forget it with the `hg revert` command:

```raw-file

output/amend-extract-badfile-after-revert.log

```

Also don't forget to remove the file:

```bash

$ rm badfile

```

Ok. Now we still have a line to extract from our commit, so let's use the handy interactive mode of `hg amend --extract` to extract lines:

```raw-file

output/amend-extract.log

```

Much better! One last thing, as the line that we extracted is still in our working directory, just like when we extracted a file: