Shortcuts for Specifying Revisions / hg tip

Shortcuts for Specifying Revisions

posted by Steve Losh on October 5, 2009

A lot of Mercurial commands allow you to specify a revision to act on. For example: hg update REV will update to revision REV, and hg diff -c REV will show you the changes made by revision REV.

The most common way to tell Mercurial which revision to act on is to use local revision numbers. For example: hg update 30 will update the working directory to revision 30.

That’s fine if you know the revision number you want to use (or don’t mind looking it up with hg log), but Mercurial has some shortcuts that can make things easier.

Hashes

The revision numbers that you use most of the time are only accurate in your local repository. Usually this isn’t a problem, but if you want to talk to someone else about a particular revision you should use the unique hash of that revision as an identifier.

You can use hg log to look up the revision’s hash — it’s printed right next to the revision number. For example:

$ hg log -r 30
changeset:   30:f7744f53cf93
...

In this case f7744f53cf93 is the hash you should use if you’re talking to someone else.

Named Branch Names

If you use named branches (created with hg branch branchname) then using branchname instead of a revision number is shorthand for: “the last revision committed in the branchname branch”.

This can come in very handy when you need to switch branches often:

$ hg update feature-branch
... work on a new feature ...
$ hg commit -m 'Add part of the new feature.'
$ hg update default
... fix a critical problem on the default branch ...
$ hg commit -m 'Fix the bug that set the servers on fire.'
$ hg update feature-branch
... go back to where you left off on the feature branch ...

It’s also useful when you want to merge (remember, hg merge can take a revision to merge with):

$ hg update default
$ hg merge --rev feature-branch
$ hg commit -m 'Merge in the new feature.'

The Current Parent

One of the more obscure tricks for specifying revisions is using . to say “the current parent of the working directory”:

$ hg commit -m 'Finish up some changes.'
$ hg log --change .
... show the changes made by the revision you just committed ...
$ hg diff --rev 12:.
... show the diff between revision 12 and the one you just committed ...
$ hg update -C .
... blow away any uncommitted changes in the working directory while
    staying at the same revision ...

The Tip’s Ancestors

If you use a negative number as a revision it means “X revisions back from the tip revision of the repository”. -1 means the tip itself, -2 means the tip’s parent, and so on.

This can get tricky once you hit some merges, but it’s useful if you just need to go back a couple of revisions from the tip.

Other Tricks

There are more ways to specify revisions. Check out hg help revisions to learn more.

If you’re a git user trying Mercurial and you miss the revision^ syntax, take a look at the parentrevspec extension which adds that syntax to Mercurial.

hg tip