• Choose a category
• All
• Classic-Fiction

$ echo third change >> myfile

$ hg commit -m 'third change'

$ hg backout --merge -m 'back out second change' 1

reverting myfile

created new head

changeset 3:d4c21ae7349f backs out changeset 1:60b1c4c78499

merging with changeset 3:d4c21ae7349f

merging myfile

0 files updated, 1 files merged, 0 files removed, 0 files unresolved

(branch merge, don't forget to commit)

If you take a look at the contents of myfile after the backout finishes, you’ll see that the first and third changes are present, but the second is not.

$ cat myfile

first change

third change

As the graphical history in Figure 9-2 illustrates, Mercurial still commits one change in this kind of situation (the box-shaped node represents the ones that Mercurial commits automatically), but the revision graph now looks different. Before Mercurial begins the backout process, it first remembers what the current parent of the working directory is. It then backs out the target changeset, and commits that as a changeset. Finally, it merges back to the previous parent of the working directory, but notice that it does not commit the result of the merge. The repository now contains two heads, and the working directory is in a merge state.

Figure 9-2. Automated backout of a non-tip change using the hg backout command

The result is that you end up “back where you were,” only with some extra history that undoes the effect of the changeset you wanted to back out.

You might wonder why Mercurial does not commit the result of the merge that it performed. The reason lies in Mercurial behaving conservatively: a merge naturally has more scope for error than simply undoing the effect of the tip changeset, so your work will be safest if you first inspect (and test!) the result of the merge, then commit it.

Always use the --merge option

In fact, since the --merge option will do the “right thing” whether or not the changeset you’re backing out is the tip (i.e., it won’t try to merge if it’s backing out the tip, since there’s no need), you should always use this option when you run the hg backout command.

Gaining More Control of the Backout Process

While I’ve recommended that you always use the --merge option when backing out a change, the hg backout command lets you decide how to merge a backout changeset. Taking control of the backout process by hand is something you will rarely need to do, but it can be useful to understand what the hg backout command is doing for you automatically. To illustrate this, let’s clone our first repository, but omit the backout change that it contains.

$ cd ..

$ hg clone -r1 myrepo newrepo

requesting all changes

adding changesets

adding manifests

adding file changes

added 2 changesets with 2 changes to 1 files

updating working directory

1 files updated, 0 files merged, 0 files removed, 0 files unresolved

$ cd newrepo

As with our earlier example, we’ll commit a third changeset, then back out its parent, and see what happens.

$ echo third change >> myfile

$ hg commit -m 'third change'

$ hg backout -m 'back out second change' 1

reverting myfile

created new head

changeset 3:b47000db73c8 backs out changeset 1:60b1c4c78499

the backout changeset is a new head - do not forget to merge

(use "backout --merge" if you want to auto-merge)

Our new changeset is again a descendant of the changeset we backed out; it’s thus a new head, not a descendant of the changeset that was the tip. The hg backout command was quite explicit in telling us this.

$ hg log --style compact

3[tip]:1 b47000db73c8 2009-05-05 06:44 +0000 bos

back out second change

2 b0ecc05c2a5d 2009-05-05 06:44 +0000 bos

third change

1 60b1c4c78499 2009-05-05 06:44 +0000 bos

second change

0 fea7474d43c3 2009-05-05 06:44 +0000 bos

first change

Again, it’s easier to see what has happened by looking at a graph of the revision history, in Figure 9-3. This makes it clear that when we use hg backout to back out a change other than the tip, Mercurial adds a new head to the repository