best practice

Mercurial with a Subversion central repository

This How-To is for developers wishing to use Mercurial (Hg) on their Windows development boxes when the source code is in a central Subversion (SVN) repository.

Install TortoiseHg.

In a Windows development environment the easiest way to get started with Hg is to install TortoiseHg. The Windows Explorer extension not only makes it easy to work with files by using icon overlays and context menus but also packages up Python, the SVN bindings and a large number of Hg extensions that will prove very useful.

If you are behind a proxy you must first configure Hg with the proxy settings. Use the TortoiseHg context menu and Global Settings > Proxy.

Working with SVN.

Given that you are working against a central SVN repository then Hg has a number of extensions that can talk to the SVN repo. I use HgSubversion. To install this extension you need to clone the hgsubversion repo:

hg clone c:\hgsvn

Use the TortoiseHg context menu and Global Settings > Edit File.

hgsubversion = c:\hgsvn

Start with a single project. It’s better to clone the whole repo, the trunk, branches and tags, rather than just a branch. This way you only need to do the clone once – clones can take a while. Create a project folder, i.e. c:\development\local\myproject, change to it and then clone the SVN repo:

hg clone sv://subversion/myproject/


It’s best to set up the ignore list for Hg now. Save this as .hgignore and copy it to the root of your local Hg clone (next to .hg).

# Mercurial .hgignore file template by
# For syntax see:
# Source:

# Visual Studio

# Subversion

# Build structure

# Misc

Local Development.

If you use local branches and merge them in your local Hg repo you won’t be able to push changes to SVN.

If you commit often then you will end up with lots of changesets to push to SVN that will make it harder to see what the intention of your update was.

A good way to solve both problems is to submit patches to the central repo. Hg has an extension for patch management called Mercurial Queues (MQ).

Mercurial Queues.

Mercurial Queues (MQ) provides patch management integrated with Hg. This is incredibly useful for packaging up a lot of small changes that you record as you work locally into a single submission to the central repo. You can also work on a number of patches concurrently.

Enable the MQ extension in Hg, TortoiseHg > Global Settings > Extensions and check ‘mq’. In the mercurial.ini set diffs to use the git format.

git = True

In the Hg Repository Explorer you can create a new patch from the latest revision. This means you will need to commit something you want to go into a patch before you can create the patch. The other way is to use the command line.

hg qnew mylatestpatch

qnew will include the latest changes found in the working directory.


One way to work with plenty of local commits but to have a single, tidy submission to the central repo is to use MQ’s qfold to create a patch.

Once you have some changesets you wish to publish you convert them into patches. In Hg Repository Explorer use the context menu on the latest changeset first: Mercurial Queues > Import Revision to MQ. Repeat for each of the changesets. Next, unapply the latest patches until just the earliest is still applied. Now at the command line use qfold. When you refresh Hg Repository Explorer you will see a single patch. Use the patch context menu’s ‘Finish Applied’ to change the patch into a single changeset you can push to the central repo.

For example, you have three changesets: 16; 17 and 18. You then create three patches: 16.diff; 17.diff and 18.diff. You unapply 17.diff and 18.diff then go to the command line:

hg qfold 17
hg qfold 18

Now you have a single patch, 16.diff, that contains all the work commited in the original three changesets.

Code Review

The Smart Bear Software company have a code review tool that they used in a huge case study with Cisco. From this they drew up some Best Practices. A summary of these is useful for our own code reviews.

  1. Review fewer than 200-400 lines of code (LOC) at a time. Beyond this the ability to find defects diminishes.
  2. Take your time with code review. Faster is not better. Keep it below 300-500 LOC per hour.
  3. You should never review code for more than 90 minutes at a stretch (although you should always spend at least five minutes reviewing code – even if it’s just one line).
  4. Author preparation eliminates the majority of defects so try to prepare notes and comments outside of the code for the review.
  5. Both author and reviewer should use a checklist as this helps to find omissions. Personal checklists are also useful.
  6. Verify that defects are actually fixed.
  7. Defects are positive. This is an opportunity to improve the code; for the author and reviewer to work as a team; for developers to unlearn bad habits; and for good mentoring. Defects must not be held against a developer in any way.
  8. Hubris matters. Reviewing a fifth to a third of your code will probably give you the maximum benefit with minimal time expenditure and reviewing 20% of your code is certainly better than none.
  9. Most effective reviews are conducted using a collaborative software tool to facilitate the review. Review Board is used for our peer review of code.