Converting from Subversion, CVS, git...

Introduction

Mercurial is able to convert repositories from other version control systems into its own format. This is especially useful if you are coming from another system and want to use Bitbucket to host your work.

Mercurial supports conversion from these systems:

  • CVS
  • Darcs
  • Git
  • Subversion
  • Monotone
  • GNU Arch
  • Bazaar

This guide will walk you through how to convert from a couple of these, namely Subversion and Git. It is worth mentioning that Darcs, Arch, Bazaar and Monotone are currently somewhat experimental, but should work fine.

The convert extension

First of all, you must enable the convert extension that ships with Mercurial.

Edit your ~/.hgrc to look like this:

[extensions]
hgext.convert =

The convert command should now be available.

Subversion

While Subversion is currently used widely in all kinds of software development projects, more and more projects may want to convert to the DVCS paradigm.

For this example, we will be converting Graham Dumpleton's excellent mod_wsgi module, which is hosted on Google code.

For Subversion specifically, Mercurial is clever enough to recognize the trunk/branches/tags directory structure used ubiquitously. When you supply an URL for the repository, Mercurial will look for a trunk directory and if it exists, it will use it as the base. If it finds branches or tags it will also attempt to name branches and tags from that.

The Subversion URL for mod_wsgi is http:modwsgi.googlecode.com/svn. Lets begin by downloading the latest revision of the repository.

NB: You may also point Mercurial directly at the remote repository, although this is not as well supported as a local starting point. If you want to do this, you can skip this step.

$ svn co http://modwsgi.googlecode.com/svn/trunk mod_wsgi
A    mod_wsgi/mod_wsgi
A    mod_wsgi/mod_wsgi/configure
[...]
A    mod_wsgi/README
Checked out revision 929.

Now that we have the latest revision of mod_wsgi (aka HEAD), we have a place we can point Mercurial to. Mercurial will automatically pick up the correct settings and download the full history from the central repository.

$ hg convert mod_wsgi mod_wsgi_hg
initializing destination mod_wsgi_hg repository
scanning source...
sorting...
converting...
589 Initial directory structure.
588 Import code from existing private source code repository.
587 Make log message about signals being ignored a warning rather than error.
586 To be consistent with mod_rewrite, %{ENV} should also look in notes and
[...]
0 Fix issue with daemon mode where error logging when using ErrorLog in
updating tags

You're done! If you cd to the newly created mod_wsgi directory, you will be entering a fully fledged, history-preserved Mercurial repository, consisting of the exact same files as the Subversion repository.

Now would be a good time to upload your repository to Bitbucket, so go ahead and create your repository on the "Create Repository" page.

Let's upload:

$ pwd
~/Work/mod_wsgi_hg
$ hg push http://bitbucket.org/jespern/mod_wsgi
pushing to http://bitbucket.org/jespern/mod_wsgi
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 589 changesets with 1021 changes to 7 files

The repository is now uploaded to our servers, and ready to use. Go check it out!

Git

Git is another Distributed Version Control System, not unlike Mercurial itself. There are times when converting is something you want to do.

For this example, we're going to use the popular will_paginate plug-in for Ruby on Rails, hosted by Github.

The repository URL is git:github.com/mislav/will_paginate.git.

Mercurial does not allow cloning remote Git repositories, so you first have to download it:

$ git clone git://github.com/mislav/will_paginate.git will_paginate 
Initialized empty Git repository in /tmp/will_paginate/.git/
remote: Counting objects: 1670, done.
remote: Compressing objects: 100% (598/598), done.
Indexing 1670 objects...
remote: Total 1670 (delta 1021), reused 1670 (delta 1021)
 100% (1670/1670) done
Resolving 1021 deltas...
 100% (1021/1021) done

Now that we have the full Git repository locally, we can convert:

$ hg convert will_paginate will_paginate_hg
initializing destination will_paginate_hg repository
scanning source...
sorting...
converting...
216 Initial WillPaginate import
215 Extra css
[...]
1 added test for parent commit (removing :include from count in ActiveRecord 2.1)
0 CHANGELOG and bump up the tiny version number to 2.3.3
updating tags

You're done! If you look in the newly created repository will_paginate_hg, you will see that the entire history, as well as branches and tags have been converted to Mercurial. As with our Subversion example you can go ahead and upload the repository to our servers.

Others

Conversion with Mercurial is easy. You can convert almost any repository to Mercurial, as easy as shown above. There is an excellent manual on the subject, you can read it by typing hg convert without specifying any arguments, or you can read the section on the Mercurial Wiki called ConvertExtension.