Mercurial Frequently Asked Questions

2.1. 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.

2.2. What is cloning, pulling, and pushing?

In many other version control systems, all developers commit changes to a single, centralized repository. In Mercurial, every developer typically works in his or her own repository. A fundamental concept of Mercurial is transferring changesets among repositories. This is accomplished through the clone, push, and pull operations (see also CommunicatingChanges).

To begin a task on an existing project, a developer will typically create a local copy of the repository using the hg clone command. This operation creates a new repository containing all the files and all of their history.

If another developer has made changes to her repository, you can pull her changes into your repository using the hg pull command. If you have made changes to your repository and you wish to transfer them to another repository (say, to a shared repository), you would do this using the hg push command.

2.3. What are branches, merges, heads, and the tip?

In the simplest case, history consists of a linear sequence of changesets. In this case, every changeset (except for the first and last) has one parent and one child. For a variety of reasons, it is possible for the history graph to split into two or more independent lines of development. When this occurs, the history graph is said to have a branch. Where a branch occurs, a changeset has two or more children.

When two lines of development are joined into a single line, a merge is said to have occurred. Where a merge occurs, a changeset has two parents. If a line of development is not merged into another, the last changeset on that line is referred to as the head of that branch. Every repository always includes one or more heads. Heads have no children. Use the hg heads command to list the heads of the current repository.

The tip is the changeset added to the repository most recently. 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 new tip. Use hg tip to show the tip of the repository.

The tip is always a head. If there are multiple heads in a repository, only one of them is the tip. Within a repository, changesets are numbered sequentially, so the tip has the highest sequence number. The word "tip" functions as a special tag to denote the tip changeset, and it can be used anywhere a changeset ID or tag is valid.

The following diagram illustrates these concepts.

The history has branched at revs 1:34ef and 4:ac98, and a merge has occurred at rev 4:ac98. Revs 5:0345, 6:19e3, and 7:8e92 are heads, and 7:8e92 is the tip.

Note that while hg tip shows the tip and hg heads shows the heads of the repository, the hg branch and hg branches commands do not list the branch changesets as described above. Instead, they show changesets corresponding to branches that have been given names. See NamedBranches.

The term "branch" has other meanings as well. See Branch for a fuller discussion.

3.1. How does merging work?

See merge

3.2. What are some best practices for distributed development with Mercurial?

See WorkingPractices

3.3. How do I import from a repository created in a different SCM?

See ConvertingRepositories for various tips.

3.4. What about Windows support?

See WindowsInstall for getting started using Windows.

3.5. Is there a GUI front-end?

See GUIClients for information on graphical merge tools and other front-ends.

4.1. What can I configure in Mercurial

See in MercurialIni.

4.2. I get an error while cloning a remote repository via ssh

If your remote repository is cloned thusly

  hg clone ssh://USER@REMOTE/path/to/repo

And, you find that after successful ssh authentication you get the error message remote: abort: repository path/to/repo not found! , then you need to know the following:

• Mercurial's remote repository syntax differs from syntax of other well known programs such as rsync, cvs - both of which use a : character to delimit USER@REMOTE from the path component (/path/to/repo).

• The path to the remote repository is relative to $HOME of USER. i.e., it is  ~USER/path/to/repo .

• Remember to use hg -v clone ssh://USER@REMOTE/path/to/repo and observe the remote command being executed via the ssh channel

4.3. I get an "ssl required" error message when trying to push changes

If you're on a network you trust you can add

[web]
push_ssl = false

in your <repository-name>/.hg/hgrc file. (Taken from HgWebDirStepByStep)

There's a reason for requiring SSL, however. If you do not trust the network you are using do not change this.

4.4. 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.

4.5. 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.

4.6. hg status shows changed files but hg diff doesn't!

hg status reports when file contents or flags have changed relative to either parent. hg diff only reports changed contents relative to the first parent. You can see flag information with the --git option to hg diff and deltas relative to the other parent with -r.

4.7. hg export or log -p shows a strange diff for my merge!

The diff shown by hg diff, hg export and hg log is always against the first parent for consistency. Also, the files listed are only the files that have changed relative to both parents.

(Are diffs of merges really always against the first parent? Doesn't hg export have a --switch-parent option? It would also be good if the docs would give the rational for hg diff and hg log not having that option (assuming they don't--the man page only mentions it for export).)

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

You've probably done an hg merge (see Merge), 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.

(Surely this can only happen if you specified specific files/directories to the revert command, right? If you specify the --all argument instead then I'd assume (hope!) the working copy state is identical to the state as recored by the primary parent and no non-primary parent changes are left. If this isn't the case then it would be very helpful if a sentence or two could be added to explain why.)

(Also note this section conflicts with the text in the man page which says there is no default selection if there are two parents: "If the working directory has two parents, you must explicitly specify the revision to revert to.")

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

4.9. 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.

Note: you might want to copy hgrc file from your old repository.

4.10. I committed a change containing nuclear launch codes, how do I delete it permanently?

If you've just committed it, and you haven't done any other commits or pulls since, you may be able to use rollback (see Rollback) to undo the last commit transaction:

$ hg rollback
rolling back last transaction

If you've made other changes but you haven't yet published it to the world, you can do something like the following:

$ hg clone -r <untainted-revision> tainted-repo untainted-repo

The strip command in the mq extension may also be useful here for doing operations in place.

This will get you a new repo without the tainted change or the ones that follow it. You can import the further changes with hg export and hg import or by using the TransplantExtension. See TrimmingHistory for possible future approaches.

If you've already pushed your changes to a public repository that people have cloned from, the genie is out of the bottle. Good luck cleaning up your mess.

“Judge Tries to Unring Bell Hanging Around Neck of Horse Already Out of Barn Being Carried on Ship That Has Sailed.” - William G. Childs

For more details, see EditingHistory.

4.11. 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

4.12. I want to get an email when a commit happens!

Use the NotifyExtension

4.13. I'd like to put only some few files of a large directory tree (home dir for instance) under mercurial's control, and it is taking forever to diff or commit

Just do a

printf "syntax: glob\n*\n" > .hgignore

or, if you are using 0.7 or below,

printf ".*\n" > .hgignore

This will make hg ignore all files except those explicitly added.

4.14. Why is the modification time of files not restored on checkout?

If you use automatic build tools like make or distutils, some built files might not be updated if you checkout an older revision of a file. Additionally a newer changeset might have an older commit timestamp due to pulling from someone else or importing patches somebody has done some time ago, so checking out a newer changeset would have to make the files older in this case.

If you need predictable timestamps you can use hg archive, which can do something like a checkout in a separate directory. Because this directory is newly created, there is nothing like switching to a different changeset afterwards, therefore the above mentioned problems don't apply here.

4.15. My merge program failed, and now I don't know what to do

If your merge program fails you'll find yourself in a state where both hg up and hg merge produce the same, unhelpful output.

abort: outstanding uncommitted merges

When this first happened, mercurial told you what to do, but if you've lost those instructions, the only way to get them back is to run "hg rollback" and repeat the action.

Why does hg merge not invoke merge again? Why the unhelpful output?

4.16. Any way to 'hg push' and have an automatic 'hg update' on the remote server?

[hooks]
changegroup = hg update >&2

This goes in .hg/hgrc on the remote repository. Output has to be redirected to stderr (or /dev/null), because stdout is used for the data stream.

4.17. How can I store my HTTP login once and for all ?

You can specify the usename and password in the URL like:

http://user:password@mydomain.org

Then add a new entry in the paths section of your hgrc file.

4.18. How can I do a "hg log" of a remote repository?

You can't. Mercurial accepts only local repositories for the -R option (see hg help -v log).

> hg log -R http://www.selenic.com/repo/hello
abort: repository 'http://www.selenic.com/repo/hello' is not local

The correct way to do this is cloning the remote repository to your computer and then doing a hg log locally.

This is a very deliberate explicit design decision made by project leader Matt Mackall (mpm). See also http://www.selenic.com/mercurial/bts/issue1025 for the reasoning behind that.

4.19. How can I find out if there are new changesets in a remote repository?

To get the changeset id of the tipmost changeset of a remote repository you can do:

> hg id -i -r tip http://www.selenic.com/repo/hello
82e55d328c8c

When it changes, you have new changesets in the remote repository.

4.20. What can I do with a head I don't want anymore?

See PruningDeadBranches

4.21. The clone command is returning the wrong version in my workspace!

Clone checks out the tip of the default (aka unnamed) branch (see NamedBranches). Ergo, you probably want to keep your main branch unnamed.

5.1. I found a bug, what do I do?

Report it to the mercurial mailing list, mercurial@selenic.com or in the bug tracker http://www.selenic.com/mercurial/bts/

5.2. What should I include in my bug report?

Enough information to reproduce or diagnose the bug. If you can, try using the hg -v and hg -d switches to figure out exactly what Mercurial is doing.

If you can reproduce the bug in a simple repository, that is very helpful. The best is to create a simple shell script to automate this process, which can then be added to our test suite.

5.3. Can Mercurial do <x>?

If you'd like to request a feature, send your request to mercurial@selenic.com. As Mercurial is still very new, there are certainly features it is missing and you can give us feedback on how best to implement them.

Be sure to see ToDo and MissingFeatures to see what's already planned and where we need help.

6.1. How do I link to the latest revision of a file?

Find the URL for the file and then replace the changeset identifier with tip.

6.2. How do I change the style of the web interface to the visually more attractive gitweb?

In hgrc set

[web]
style = gitweb

To switch back to the default style specify "style = default" (see hgbook).

7.1. What limits does Mercurial have?

Mercurial currently assumes that single files, indices, and manifests can fit in memory for efficiency.

There should otherwise be no limits on file name length, file size, file contents, number of files, or number of revisions (see also RepoSamples for the sizes of some example repositories.)

The network protocol is big-endian.

File names cannot contain the null character or newlines. Committer addresses cannot contain newlines.

Mercurial is primarily developed for UNIX systems, so some UNIXisms may be present in ports.

Mercurial encodes filenames (see CaseFolding, CaseFoldingPlan) when storing them in the repository. Uppercase characters in filenames are encoded as two characters in the filename in the repository ("FILE" → "_f_i_l_e"). On Windows, you might then hit the maximum allowed path name length for files in the repository (see also Issue839).

7.2. How does Mercurial store its data?

The fundamental storage type in Mercurial is a revlog. A revlog is the set of all revisions of a named object. Each revision is either stored compressed in its entirety or as a compressed binary delta against the previous version. The decision of when to store a full version is made based on how much data would be needed to reconstruct the file. This lets us ensure that we never need to read huge amounts of data to reconstruct a object, regardless of how many revisions of it we store.

In fact, we should always be able to do it with a single read, provided we know when and where to read. This is where the index comes in. Each revlog has an index containing a special hash (nodeid) of the text, hashes for its parents, and where and how much of the revlog data we need to read to reconstruct it. Thus, with one read of the index and one read of the data, we can reconstruct any version in time proportional to the object size.

Similarly, revlogs and their indices are append-only. This means that adding a new version is also O(1) seeks.

Revlogs are used to represent all revisions of files, manifests, and changesets. Compression for typical objects with lots of revisions can range from 100 to 1 for things like project makefiles to over 2000 to 1 for objects like the manifest.

7.3. How does Mercurial handle binary files?

See BinaryFiles.

7.4. What about Windows line endings vs. Unix line endings?

See EncodeDecodeFilter.

7.5. What about keyword replacement (i.e. $Id$)?

See KeywordPlan and KeywordExtension.

7.6. How are Mercurial diffs and deltas calculated?

Mercurial diffs are calculated rather differently than those generated by the traditional diff algorithm (but with output that's completely compatible with patch of course). The algorithm is an optimized C implementation based on Python's difflib, which is intended to generate diffs that are easier for humans to read rather than be 'minimal'. This same algorithm is also used for the internal delta compression.

In the course of investigating delta compression algorithms, we discovered that this implementation was simpler and faster than the competition in our benchmarks and also generated smaller deltas than the theoretically 'minimal' diffs of the traditional diff algorithms. This is because the traditional algorithm assumes the same cost for insertions, deletions, and unchanged elements.

7.7. How are manifests and changesets stored?

A manifest is simply a list of all files in a given revision of a project along with the nodeids of the corresponding file revisions. So grabbing a given version of the project means simply looking up its manifest and reconstructing all the file revisions pointed to by it.

A changeset is a list of all files changed in a check-in along with a change description and some metadata like user and date. It also contains a nodeid to the relevant revision of the manifest.

7.8. How do Mercurial hashes get calculated?

Mercurial hashes both the contents of an object and the hash of its parents to create an identifier that uniquely identifies an object's contents and history. This greatly simplifies merging of histories because it avoid graph cycles that can occur when a object is reverted to an earlier state.

All file revisions have an associated hash value (the nodeid). These are listed in the manifest of a given project revision, and the manifest hash is listed in the changeset. The changeset hash (the changeset ID) is again a hash of the changeset contents and its parents, so it uniquely identifies the entire history of the project to that point.

7.9. What checks are there on repository integrity?

Every time a revlog object is retrieved, it is checked against its hash for integrity. It is also incidentally doublechecked by the Adler32 checksum used by the underlying zlib compression.

Running 'hg verify' decompresses and reconstitutes each revision of each object in the repository and cross-checks all of the index metadata with those contents.

But this alone is not enough to ensure that someone hasn't tampered with a repository. For that, you need cryptographic signing.

7.10. How does signing work with Mercurial?

Take a look at the hgeditor script for an example. The basic idea is to use GPG to sign the manifest ID inside that changelog entry. The manifest ID is a recursive hash of all of the files in the system and their complete history, and thus signing the manifest hash signs the entire project contents.

7.11. What about hash collisions? What about weaknesses in SHA1?

The SHA1 hashes are large enough that the odds of accidental hash collision are negligible for projects that could be handled by the human race. The known weaknesses in SHA1 are currently still not practical to attack, and Mercurial will switch to SHA256 hashing before that becomes a realistic concern.

Collisions with the "short hashes" are not a concern as they're always checked for ambiguity and are still long enough that they're not likely to happen for reasonably-sized projects (< 1M changes).

7.12. How does "hg commit" determine which files have changed?

If hg commit is called without file arguments, it commits all files that have "changed" (see Commit). Note however, that Mercurial doesn't detect changes that do not change the file time or size (This is by design. See also msg3438 in issue618 and DirState).