Mercurial Frequently Asked Questions

Common Problems

I did an hg pull and my working directory is empty!

There are two parts to Mercurial: the repository and the working directory. hg pull pulls all new changes from a remote repository into the local one but doesn't alter the working directory.

This keeps you from upsetting your work in progress, which may not be ready to merge with the new changes you've pulled and also allows you to manage merging more easily (see below about best practices).

To update your working directory, run hg update. If you're sure you want to update your working directory on a pull, you can also use hg pull -u. This will refuse to merge or overwrite local changes.

I want to retrieve an old version of my project, what do I do?

You want hg update -C <version>, which will clobber your current version with the requested version.

You don't want hg revert <version>, which reverts changes in your working directory back to that version, but keeps the current parents for the next checkin. This command exists for undoing changes in current versions, not for working on old versions.

I did an hg revert and my working directory still has changes in it!

You've probably done an hg update -m, which means your working directory now has two parents according to hg parents. A subsequent hg revert will revert your working directory back to the primary parent, thus leaving you with the differences between the two parents. hg update -C will revert the left files.

If you're trying to switch between revisions in history, you probably want hg update -C.

I want a clean, empty working directory

The easiest thing to do is run hg clone -U which will create a fresh clone without checking out a working copy.

I tried to check in an empty directory and it failed!

Mercurial doesn't track directories, it only tracks files. Which works for just about everything, except directories with no files in them. As empty directories aren't terribly useful and it makes the system much simpler, we don't intend to fix this any time soon. A couple workarounds:

• add a file, like "this-dir-intentionally-left-blank"
• create the directory with your Makefiles or other build processes

I want to get an email when a commit happens!

See CommitHook for an example.

Terminology

What are revision numbers, changeset IDs, and tags?

Mercurial will generally allow you to refer to a revision in three ways: by revision number, by changeset ID, and by tag.

A revision number is a simple decimal number that corresponds with the ordering of commits in the local repository. It is important to understand that this ordering can change from machine to machine due to Mercurial's distributed, decentralized architecture.

This is where changeset IDs come in. A changeset ID is a 160-bit identifier that uniquely describes a changeset and its position in the change history, regardless of which machine it's on. This is represented to the user as a 40 digit hexadecimal number. As that tends to be unwieldy, Mercurial will accept any unambiguous substring of that number when specifying versions. It will also generally print these numbers in "short form", which is the first 12 digits.

You should always use some form of changeset ID rather than the local revision number when discussing revisions with other Mercurial users as they may have different revision numbering on their system.

Finally, a tag is an arbitrary string that has been assigned a correspondence to a changeset ID. This lets you refer to revisions symbolically.

What are branches, heads, and the tip?

The central concept of Mercurial is branching. A 'branch' is simply an independent line of development. In most other version control systems, all users generally commit to the same line of development called 'the trunk' or 'the main branch'. In Mercurial, every developer effectively works on a private branch and there is no internal concept of 'the main branch'.

Thus Mercurial works hard to make repeated merging between branches easy. Simply run hg pull and hg update -m and commit the result.

'Heads' are simply the most recent commits on a branch. Technically, they are changesets which have no children. Merging is the process of joining points on two branches into one, usually at their current heads. Use "hg heads" to find the heads in the current repository.

The 'tip' is the most recently changed head, and also the highest numbered revision. If you have just made a commit, that commit will be the tip. Alternately, if you have just pulled from another repository, the tip of that repository becomes the current tip.

The 'tip' is the default revision for many commands such as update, and also functions as a special symbolic tag.

General Usage

How does merging work?

The merge process is simple. Usually you will want to merge the tip into your working directory. Thus you run hg update -m and Mercurial will incorporate the changes from tip into your local changes.

The first step of this process is tracing back through the history of changesets and finding the 'common ancestor' of the two versions that are being merged. This is done on a project-wide and a file by file basis.

For files that have been changed in both projects, a three-way merge is attempted to add the changes made remotely into the changes made locally. If there are conflicts between these changes, the user is prompted to interactively resolve them.

Mercurial uses a helper tool for this, which is usually found by the hgmerge script. Example tools include tkdiff, kdiff3, and the classic RCS merge.

After you've completed the merge and you're satisfied that the results are correct, it's a good idea to commit your changes. Mercurial won't allow you to perform another merge until you've done this commit as that would lose important history that will be needed for future merges.

What are some best practices for distributed development with Mercurial?

First, merge often! This makes merging easier for everyone and you find out about conflicts (which are often rooted in incompatible design decisions) earlier.

Second, don't hesitate to use multiple trees locally. Mercurial makes this fast and light-weight. Typical usage is to have an incoming tree, an outgoing tree, and a separate tree for each area being worked on.

The incoming tree is best maintained as a pristine copy of the upstream repository. This works as a cache so that you don't have to pull multiple copies over the network. No need to check files out here as you won't be changing them.

The outgoing tree contains all the changes you intend for merge into upsteam. Publish this tree with hg serve or hgweb.cgi or use