CIT 594 Getting Started with Mercurial
Spring 2011, David Matuszek

Mercurial is a distributed version control system (DVCS), similar to Git, but very different from older version control systems such as Subversion and CVS. The idea is that any number of people can work on adding to and revising the same documents. A history is kept, so that you can go back to any previously saved version, at any time. Our interest here is in developing Java programs, preferably (but not necessarily) in Eclipse.

The chemical symbol for the element mercury is Hg. At the command line, hg is used to refer to Mercurial.

Mercurial is, first and foremost, a command-line program. You can use it directly from the command line. Keep this in mind when you read about the various GUI front-ends to Mercurial. They all use (mostly) the same terminology, and they may all look different, but every Mercurial GUI is just a front end to command-line Mercurial.

Installing Mercurial

As Eclipse plugin

There is an Eclipse plugin, MecurialEclipse (formerly hgEclipse). This provides a nice GUI interface to Mercurial's features. What the web page doesn't tell you, though, is that you need to have Mylyn already installed. If you already have or can install Mylyn, well and good; if not, you might find it easier to download a version of Eclipse that already has it installed (Eclipse IDE for Java Developers, or Eclipse IDE for Java EE Developers).

On Windows 7, I already had Mylyn, and the plugin just worked.

On Mac OS X 3.6.6, I had to install the Mylyn plugin. Then I checked to make sure Python 2.6 was installed. Then I had to install Mercurial. Then I had to tell the MercurialEclipse plugin where to find Mercurial (/usr/local/bin/hg). Then I had to create a file named .hgrc in my home directory with this information:

# This is a Mercurial configuration file.
username = Firstname Lastname <>

Then it worked. YMMV.

If you are a Linux user, you have some spiffy Linux-version-specific command to do all this stuff, and you know what to do. Good luck. Don't get eaten by a grue.

For the command line

Other GUI front ends

Other software

Mercurial is very good at merging changes made by different people, but sometimes people make incompatible changes (to the same lines in the same file). Then you have to manually compare the files, and decide what to keep and what to throw away.

Learning Mercurial

The best Mercurial tutorial is Hg Init by Joel Spolsky. IMHO.

Here are some other good articles and tutorials that I've found. I've tried to put them in order, simplest to most detailed. I have not found anything worth mentioning that is specifically about the Eclipse plugin.

Intro to Distributed Version Control (Illustrated)
This is a good conceptual article, and a good thing to read first. It describes the concepts behind Mercurial (which is a distributed version control system, DVCS) and how it differs from a non-distributed system, such as CVS or Subversion. It's okay if you don't instantly understand all the concepts presented here--they will become clearer after you look at some examples.
Introduction to Version Control with Mercurial
This has a link (labeled Download the Latest Version) to an 18-page pdf file, mostly pictures, using the TortoiseHg GUI for Mercurial. Even if you're using some different interface, the ideas are all the same. This is a good first introduction, and covers the concepts of repository, revision, changeset, and the add, clone, and commit commands (but not, oddly enough, push, pull, or merge).
A Tutorial on Using Mercurial
This is ten (HTML) pages long, and describes using Mercurial at the command line.
Basic Mercurial
A much longer tutorial.
Mercurial: The Definitive Guide
This is a complete online book on Mercurial.
hg: Mercurial source code management system
An alphabetical list of commands, with descriptions and command flags.


Bitbucket is a web hosting service for Mercurial repositories. It is free for up to five users and an unlimited number of repositories. Most of the other hosting services are free for open source projects, but not nearly as suitable for student projects. Signing up is painless. In addition, Bitbucket 101 is a decent tutorial.