Mercurial: The Definitive Guide

Dealing with Committed Changes

Consider a case where you have committed a change a, and another change b on top of it, and you then realize that change a was incorrect. Mercurial lets you “back out” an entire changeset automatically, and building blocks that let you reverse part of a changeset by hand.

Before you read this section, here’s something to keep in mind: the hg backout command undoes the effect of a change by adding to your repository’s history, not by modifying or erasing it. It’s the right tool to use if you’re fixing bugs, but not if you’re trying to undo some change that has catastrophic consequences. To deal with those, see Changes That Should Never Have Been.

Backing Out a Changeset

The hg backout command lets you “undo” the effects of an entire changeset in an automated fashion. Because Mercurial’s history is immutable, this command does not get rid of the changeset you want to undo. Instead, it creates a new changeset that reverses the effect of the to-be-undone changeset.

The operation of the hg backout command is a little intricate, so let’s illustrate it with some examples. First, we’ll create a repository with some simple changes.

$ hg init myrepo
$ cd myrepo
$ echo first change >> myfile
$ hg add myfile
$ hg commit -m 'first change'
$ echo second change >> myfile
$ hg commit -m 'second change'

The hg backout command takes a single changeset ID as its argument; this is the changeset to back out. Normally, hg backout will drop you into a text editor to write a commit ...