Getting Started with Mercurial

The version control system (VCS) debate is one of the less heated "holy wars" in the Linux/Unix world. Most of the conversation revolves around Git vs. Subversion vs. CVS, but other systems may be a better fit for your needs. For instance, Mercurial is written in Python and C, which makes it easily hackable if you need some functionality the project doesn't offer already. It's also fast. And it has other advantages that make it the choice of popular open source projects such as Mozilla, OpenOffice.org, Dovecot and Vim.

I read somewhere an interesting comparison that said "Git is McGyver, Mercurial is James Bond"; in other words, while Git is a collection of tools like git-pull, git-merge, and git-checkout that do most everything except repair your sink, Mercurial is one thing, does one thing, and does it well. And it's easy to learn, too.

Mercurial runs on Mac OS X, Windows, BSD, Linux/Unix, and Solaris. Widely used Linux distributions such as Debian, Fedora, and Gentoo all offer simple ways to install Mercurial from binary packages, but since it's written mainly in Python, it's easy to install on any system that already has Python 2.x installed.

It looks like Matt Mackall, Mercurial's developer, is a chemistry fan, because instead of being called "mercurial," the application's executable is hg, the chemical symbol for the element Mercury. To see how it works, we'll start by cloning the Vim project's repository, with the command

hg clone https://vim.googlecode.com/hg/ vim

Mercurial creates a directory called vim and populates it with the vim source tree. If you later want to update the cloned repository, use

hg pull && hg update

The clone, pull, and update commands are only for passive, read-only work with a repository. You can, of course, also use Mercurial for your own projects. Say you have a directory called myproject that contains a file named hello.c, and you want to add a file world.c and manage the code with a VCS. To make the project Mercurial-aware, run the following commands:

hg init
touch world.c
hg add world.c
hg commit -m "Adding the world.c file"

If you run ls -a in myproject you will see a directory named .hg, where Mercurial stores the data it needs. The -m flag stands for message, to let your future colleagues know what you did, and for good housekeeping. Now, after someone pulls your changes, he can see the actual revision by running the command hg parents.

Any VCS lets users view the history of the repository they're working on. The command to do that in Mercurial is hg log, which optionally can take a -v (for verbose) or --debug option. Verbose displays two additional fields: files, which lists the modified files, and description, listing the complete changeset. --debug offers even more detail.

To see a specific changeset, you can use -r with a numeric argument, using the digit(s) following "changeset" and preceeding the colon:

hg log
[...]
changeset:   3:6ea9da2bf202
user:        vimboss
date:        Sun Jun 13 13:18:32 2004 +0000
summary:     updated for version 7.0001

changeset:   2:310da3e1e6c2
parent:      0:770908d1cb47
user:        vimboss
date:        Sun Jun 13 13:02:36 2004 +0000
summary:     updated for version 7.0001

changeset:   1:babbc735b80e
branch:      vim
tag:         start
user:        vimboss
date:        Sun Jun 13 12:29:53 2004 +0000
summary:     This is the experimental Vim 7 code.  Much work to be done...
[...]
hg log -r3
changeset:   3:6ea9da2bf202
user:        vimboss
date:        Sun Jun 13 13:18:32 2004 +0000
summary:     updated for version 7.0001

Use -p in conjunction with -r to see what patches were applied in a specific revision. Going back to our hello repository, say you want to modify a file. After saving the changes, you can run hg status, and you'll see an M next to the file. That stands for "Modified," and it tells you that the file was altered on your side, but not committed. Use the hg diff command to make sure you made the right changes. Use hg revert if you don't like what you've done, or hg ci (check in) to push the changes. At that point you can fill in a commit message. After you save the file and quit the editor, hg status should show there are no differences between the local copy and the repository.

With Git, you can alter revision history. With Mercurial,once you have committed something, it's there – period. People have strong personal opinions about this design choice; I personally am a big fan.

Advanced Usage

You might want to clone a Mercurial repository, perhaps for good housekeeping, because you don't want to mix unrelated changes. Use a command like hg clone ../hello ../hello-new. After you've done that, you can see the tip (the most recent changeset) in each by using the hg tip command. If need be, at any point in the future, you can pull changes from the other repository. As we did earlier, make sure you also use update after a pull, because Mercurial doesn't update by default as other systems do.

If you wanted, for instance, to send someone who's not using Mercurial evidence of what you've done, you can export changes to a file or repository by using the export command:

hg export tip -o tip.txt

Should you want to combine two separate changesets into one, Mercurial makes merging less horrible than other VCS software. The command is hg merge. I recommend using hg glog (graphlog) and hg annotate (to see changelog info per line) as helpers in your merging adventures. If you run into conflicts when you merge, because you've worked on the same file as others at the same time, you'll find they're easy to resolve, but they require a little bit of interaction. Type hg status to see the problem files and edit accordingly, then, once you've finished resolving the conflicts, use hg resolve to let Mercurial know you solved the issue.

If all of the above makes you want to move to Mercurial, or at least give it a try, Mercurial offers extensions to help you migrate from other VCS systems, including Subversion, CVS, Git, Darcs, VSS, Monotone, Bazaar, and Perforce.

TortoiseHG

From all of the above, you might get the impression that Mercurial is solely a command-line tool. Not so – a package called TortoiseHG provides a graphical user interface to Mercurial for users running Linux, Windows, or Mac OS X. It integrates well with GNOME's Nautilus file manager, and it also offers a CLI interface named thg, can directly set some options at startup, like verbosity, or start some specific operation.

[caption id="attachment_98042" align="alignnone" width="618" caption="Cloning a repository with TortoiseHG"][/caption]

To get started in TortoiseHG by cloning a repository, enter the address and the location where you want to put the code in (see figure). thg creates the command-line equivalent in the "Hg command" field, which you can edit if you want to. TortoiseHG is a nicely designed program; even though I usually prefer the command line, I personally find it useful to look at history.

All of the above should give you an idea why Mercurial is a popular VCS option. It's more powerful than the older generation of centralized VCSes, yet simpler than Git. If you suspect you could be more productive with a different VCS than you're currently using, or you want to get your feet wet with your first such application, it's worth giving Mercurial a try. And if you come from Git and miss hosting sites like Gitorious or GitHub, Mercurial has you covered with Bitbucket.

Follow @openlogic
Follow @CloudSwing

This work is licensed under a Creative Commons Attribution 3.0 Unported License
.Follow @openlogic
Follow @OSCloudServices

This work is licensed under a Creative Commons Attribution 3.0 Unported License
.