Assembla DocumentationPublic Space

Mercurial is a new open source version control system based on the distributed model. In Mercurial, as in Subversion or CVS, developers work on a local working directory. However, unlike centralized solutions, Mercurial also stores a copy of the entire project history on each developer's machine. In this way, developers can work in parallel, even without a network connection.

Like Subversion, and unlike CVS, Mercurial uses the notion of change sets. Each revision is a snapshot of the project at a given point in time. When you commit your changes, you create a new revision. Like Subversion, Mercurial naturally benefits from fast tags, good support for binary files, and the other advantages related to the use of change sets.

Unlike Subversion, however, when you commit changes in Mercurial, you only create a new revision in your local repository (which, given Mercurial is based a distributed model, is considered to be just as good a repository as anyone else's). Let's take a minute to see how this works.

See a video overview here.

Add Mercurial to your workspace

How to find the Mercurial tool: Your Workspace>Admin Tab>Tools Tab>Add Trac and Mercurial

Setting up your own Mercurial repository

The first thing you do when starting a project in Mercurial is to "clone" your own local copy of the project. Not surprisingly for a distributed version control system, you can access a Mercurial repository via HTTP. In Listing 13, I have created a copy of the Mercurial project itself.

Listing 13. Cloning a local copy of the Mercurial repository

$ hg clone http://www.selenic.com/repo/hg
destination directory: hg
destination directory: hg
requesting all changes
adding changesets
adding manifests
adding file changes
added 5027 changesets with 9501 changes to 665 files
583 files updated, 0 files merged, 0 files removed, 0 files unresolved

Once you've obtained a local copy, modifying existing files and adding new ones is intuitive, using commands such as hg add, hg remove and hg rename. The hg status command, like the equivalent Subversion and CVS commands, lets you see at a glance what has been modified in your project files, as compared to your local repository copy.

Listing 14. Familiar operations done in Mercurial

$ hg add LocallyAddedFile.java 
$ hg status 
M LocallyModifiedFile.java
A LocallyAddedFile.java

Likewise, you submit changes to your local copy of the repository using the hg commit command, as shown here:

$ hg commit -m "Some minor changes"
No username found, using 'wakaleo@taronga' instead

Push, pull, propagate

Note that the hg commit command updates your local repository copy. Because there is no central server to update, you alone will now have an up-to-date repository. This is the major difference between a distributed version control system and a centralized system like CVS or Subversion.

To update another repository, you need to propagate your changes onto this repository using the hg push command. Alternatively, another developer could fetch your changes into his or her own local repository copy using the hg pull command. For example, suppose Jill has made some changes that you need to integrate into your source code. To do this, you would "pull" her changes from her machine, like so:

$ hg pull http://jill@jillsmachine

Merging and branching

Once you have fetched the changes from another repository, you can merge them into your own repository using the hg merge command. After the merge, you need to commit the merged code to your local repository, as follows:

$ hg merge
$ hg commit

As with any merging, conflicts can arise. When conflicts do happen, Mercurial makes no attempt to merge the two files (unlike Subversion or CVS). Instead, it indicates the conflicting files and leaves it up to you to choose your favorite graphical merging tool to do the job.

If you don't specify where you are pulling your changes from, Mercurial will assume you want to get them from the original repository that you used to clone your local copy. In this case, the original repository acts a bit like a central server. This also applies for the hg push command, as shown here:

Listing 15. Pushing changes into the original repository

$ hg push
*pushing to http://buildserver.mycompany.com/mercurial/repo/myproject
searching for changes
adding changesets
adding manifests
adding file changes
added 2 changesets with 3 changes to 2 files

Branching is handled simply by cloning a new copy of your local repository. Tags are well-implemented: in fact, they are simply references to a particular change set, which you can create using the hg tag command.

Listing 16. Tagging and branching

$ tag "release candidate 1"
$ hg tags
tip                                2:87726d51f171
release candidate 1                1:1d05b948ba76

Mercurial is a young tool with some refreshing new features, such as simple change-set tagging. Like other distributed version control tools, its user base is smaller than that of a conventional tool like CVS or Subversion. IDE support for Mercurial is also more limited than for either CVS or Subversion, though the Mercurial Eclipse plugin provides some basic IDE integration.

By John Ferguson Smart, JavaWorld.com, 09/18/07