Convert from Subversion to Mercurial

This page discusses the options for converting from Subversion to Mercurial.

If you want to want import a working copy of your code (i.e. no history) from Subversion into Bitbucket Cloud, the Bitbucket importer provides a simpler mechanism for doing so. Please see the instructions on Importing Code into your Bitbucket Repository instead.

This page

Related pages

Goodbye Subversion, Hello Mercurial: A Migration Guide
Atlassian blog post describing the migration from Subversion to Mercurial.

Option 1: The hgsubversion Extension – Recommended

The hgsubversion extension is a user-contributed extension, not distributed with Mercurial. We recommend this extension.  Please refer to the hgsubversion extension guide for download sites and usage instructions.

Option 2: Mercurial's convert extension

This extension is distributed with Mercurial. Refer to the documentation:

  • Enter hg convert without specifying any arguments to read the Mercurial manual.
  • Read about the ConvertExtension on the Mercurial Wiki.

Enabling the convert Extension

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

Edit your ~/.hgrc to look like this:

hgext.convert =

The convert command should now be available.


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 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 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...
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_hg 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
$ hg push
pushing to
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!

If this last step fails you might also need to run the hg update command before hg push as shown in the following example:

$ pwd
$ hg update
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg push
pushing to
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 589 changesets with 1021 changes to 7 files

The output might look different than this example, however the order of commands is the same.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport