Mercurial for beginners

Printer-friendly versionPrinter-friendly version


Given the increasing popularity of the Mercurial version control system (and the fact that I'm using it more and more these days), here's a quick tutorial for people who simply want to check out and work with a Mercurial repository; it won't cover creating your own repo or committing changes, just working with someone else's repository.

It's your responsibility to install Mercurial on your (Linux?) system -- on Ubuntu, that would involve running:

$ sudo apt-get install mercurial

On other Linux distros, it's your job to figure out which package to install but it's a good bet it's just "mercurial," at which point you'll use the hg commmand from then on.

And why would you want to know this?

Unsurprisingly, you want to check out someone's Mercurial repo if you want to keep up with their latest development commits and track their most recent work. If you don't want to do that, then there's probably little value in following their repository.

Checking out a repository

I'm currently working with three Mercurial checkouts, so I'm just going to pick the smallest as a working example to demonstrate simple Mercurial usage. Here's how to check out the repository corresponding to Nuxeo's Digital Asset Management (DAM) software (my other two checkouts are significantly larger so I'm ignoring them):

$ hg clone

After a minute or two of downloading, this will give you a directory named nuxeo-dam in your current directory, at which point you can cd into that directory and we can get started.

Branches and tags

Your Mercurial checkout might consist of a number of branches, as well as a number of tags. First, you can examine your current branch and the set of all branches with:

$ hg branch
develop    <--- current development branch
$ hg branches
develop                      671:9c52da2250ff
1.0-beta                     431:b795ce621653
DAM-181                      239:366875669cef
DAM-213                      205:21c67297f7f7
minimal-project                7:526c1a840e79
NXP-4792-DAM-467-video-refactoring 615:679081992b79 (inactive)
DAM-357                      598:9e637c5186d1 (inactive)
1.0                          572:0afefc3970dc (inactive)
DAM-449                      566:d27e91c25145 (inactive)
... snip ...

It might be that you want to be working with a specific branch but, unless you have a reason for that, you probably want to stick with whatever branch has a name like "develop" or "development" or "master" or something similar, so that you're staying on top of the absolutely latest commits.

In addition, at times, you might want to view your checkout as it was tagged at some point in the past. You can view the tags with:

$ hg tags
tip                              671:9c52da2250ff
release-1.0                      568:2f07379e3737
release-1.0-beta                 430:7a000fb522dc

but, again, unless you have a good reason to be working with an older version of the repository, you probably just want to stick with the tag labelled "tip," which represents the latest version of the current branch.

In other words, if you simply check out someone's Mercurial repository and cd into it, you're probably right where you want to be.

Updating on a regular basis

To stay on top of the latest commits to the repository, you can just:

$ hg pull -u

In addition, before you pull, you can check if there are any outstanding commits you'd be receiving with:

$ hg incoming

Examining the state of your checkout

There are a number of commands you can use to examine the progression of work in the Mercurial repository.

Checking the "tip"

$ hg tip
changeset:   671:9c52da2250ff
branch:      develop
tag:         tip
user:        Thomas Roger 
date:        Mon Jun 28 00:15:42 2010 +0200
summary:     DAM-499: add importer dependencies to distributions. \
  New profile to include JAX-RS importer modules

The above shows you that the latest commit that you've pulled down is change 671, who committed it, when it was committed and a short summary.

In addition, you can ask for the actual "diff" output of that commit by adding the -p option which (for quite a number of Mercurial commands) specifies to show the "patch" information corresponding to that commit:

hg tip -p
changeset:   671:9c52da2250ff
branch:      develop
tag:         tip
user:        Thomas Roger 
date:        Mon Jun 28 00:15:42 2010 +0200
summary:     DAM-499: add importer dependencies to distributions. \
  New profile to include JAX-RS importer modules

diff -r 6b483e7f2fd6 -r 9c52da2250ff nuxeo-dam-distribution/pom.xml
--- a/nuxeo-dam-distribution/pom.xml    Sat Jun 26 16:14:42 2010 +0200
+++ b/nuxeo-dam-distribution/pom.xml    Mon Jun 28 00:15:42 2010 +0200
@@ -35,6 +35,9 @@
+      http-importer
... and so on ...

As an aside, for any Mercurial command, you can get help with:

$ hg help [command]

Checking the log

If you want to see the repository history, just use one of:

$ hg log
$ hg log -p     [add patch info as well]

You can also check the log and contents of any other revision if you have the revision number:

$ hg log -r667 -p
... log entry and diff printed here ...

If you want to see what else this command can do, there's always:

$ hg help log

Making some local changes

If you're following someone's development branch because you want to test the absolutely latest (pre-release) version of the software, it's entirely possible that you might want to make some temporary changes to your local working copy to see how that would affect the software. For example, in this current Nuxeo DAM checkout, let's say you made some innocuous changes to the README.txt file. You could examine your local diffs (throughout the entire source tree) with:

$ hg diff
diff -r 9c52da2250ff README.txt
--- a/README.txt	Mon Jun 28 00:15:42 2010 +0200
+++ b/README.txt	Fri Jul 02 07:20:39 2010 -0400
@@ -1,3 +1,6 @@
+This line added by rday.
+This one, too.
 Nuxeo Digital Asset Management application

At this point, perhaps you'd rebuild the software (locally, of course) and test the effect of your change (assuming you made a more meaningful change than the one above).

Once you're done testing your local changes, you can discard those changes throughout your working copy with:

$ hg revert -a

As always:

$ hg help revert

Cleaning out generated and untagged files

One final point is worth covering. If you're using your checkout to build and test someone's else code base, chances are that you'll be generating temporary files inside your local working copy and, after testing, you might want to delete those temp files -- that is, delete any content within your working copy that doesn't represent an official entry in the repository.

You can easily generate the list of untagged files with:

$ hg status -nu

and use whatever incantation you want to drive that list of files into a Linux command that removes them all, such as

$ hg status -nu | xargs rm -f

or something similar.

And what else?

At this point, that should be enough to get you going as a simple Mercurial user. For more tutorial, I suggest starting here and following links.

We know

We're aware of the time and budget pressures at most companies, normally accompanied by the plaintive cry from management of, "Yes, I know we need training on that topic, but I just can't afford to send my entire team away for three (or four or five) days to get it!" And that's where we come in.


The main focus at Crashcourse is to offer a choice of intense, 1-day, hands-on courses on specific topics in Linux and open source. And given that we already have the laptops for the delivery of that training, the idea is to show up early, set up a classroom, then spend the day teaching exactly the topic you're interested in. No travel time, and no wasted classroom time.


If we don't already have a course that addresses the topic you're interested in, drop us a note and we'll see what we can do -- our content providers can almost certainly put together a course that's precisely what you're after.

The difference

While there are a variety of sources for Linux and open source training, we at Crashcourse are taking a slightly different approach. Our philosophy is simple: exactly the training you want, and no wasted time or travel to get it.