SVN is the centralized repository system that many developers should have been familiar with. Mercurial (Hg) is one of the latest distributed repository system that is gaining popularity, besides Bazaar and Git. TortoiseSVN and TortoiseHg are GUI tools to manage SVN and Hg respectively in windows. That said, this note would apply mostly to windows users.

I would demonstrate two options to the migration but the outcomes might not be the same and I would detail the difference of each.

A. Using Convert extension

This method convert the whole SVN repository into a Hg repository. No worries, full history from the SVN will be copied and you will be working with your Hg repository as though nothing had changed. The Convert extension is installed by default in TortoiseHg, so you just have to enable it. To enable it, open the global settings of TortoiseHg, go to the extension tab, and put a tick beside the Convert extension.

Enable Convert extension

For the next step, you have to use the command line. Suppose your repository is on your hard disk, you would type:

hg convert file:///path-to-svn-repo

or if it is on a server:

hg convert http://url-to-svn-repo

Some additional options include:

  • svn.trunk - Relative path to the trunk (default: “trunk”)
  • svn.branches - Relative path to tree of branches (default: “branches”)
  • svn.tags - Relative path to tree of tags (default: “tags”)
  • svn.startrev - Start subversion revision (as of 963000ed8cac, > 0.9.5). Work for single branches conversions only.

And you use it as follow:

hg --config convert.svn.trunk=whatsoever convert

B. Using HgSubversion

By using this method, the main repository of your project remains as an SVN repository, while you can use Hg to manage your personal addition or modification on your hard drive. You should choose HgSubversion over the Convert extension when you have no control over the main repository or when you simply couldn’t persuade others to change from SVN to Mercurial.

The method gives you a fully-functional distributed version control system, where you maintain a Hg repository on your local computer to commit your own modification before pushing them to the central SVN repository. You can also work the other way round, i.e. pull the changes from the SVN repository to your Hg repository. Push and Pull are two essential concepts in a distributed version control system, which involve moving changes from one repository to another in either direction.

Steps to use:

  1. Install HgSubversion by cloning it.

    hg clone http://bitbucket.org/durin42/hgsubversion/ C:/Users/Public/hgsubversion

  2. Configure Hg extension by editing the configuration file (usually %USER_HOME%/mercurial.ini). Add the following lines:

    [extensions]
hgsubversion = C:/Users/Public/hgsubversion/hgsubversion

  3. Start cloning your SVN repository. For example:

    hg clone http://google-web-toolkit.googlecode.com/svn gwt-hg

  4. Pull changes from the SVN repository as normal using hg pull.

  5. Before pushing to the central SVN repository, you should use hg rebase –svn. Then hg push as normal to push the changes back to the SVN repository.

Yet, you might ask: Why should I migrate from SVN to Mercurial after all?

Firstly, SVN is simply sounds…outdated! SVN is a thing of the previous decade, and people in the open source world are switching to Mercurial or Git.

Using Mercurial encourages you to commit more, due to the flexibility of working with Hg remotely. Every user has a local repository, complete with project history and branches, etc. You can commit to this local repository even when not connected to the central repository. With more frequent commits, you avoid messing up with a large portion of unsaved work.

Compared to using only one central repository, you generally have more backups by using Mercurial. Every user holds a clone of the project’s repository. If your central repository is corrupted or lost, you may still recover the whole repository from every individual users.

So, finally…Should you decide on using Mercurial for your projects, below are some good tutorials to get you started:

Hg Init: a Mercurial tutorial by Joel Spolsky