From Mercurial to Git

In the last weeks, I migrated all my personal projects from Mercurial to Git (they remain hosted at BitBucket.org for now, under the same URLs).

There was no special reason for doing that, other than my thinking that it was the right thing to do now…

The Past

When I started my first projects, I didn’t use any version control system (VCS) at all; but after a while (more out of interest then need, since it were just simple one boy projects), I began using Subversion (SVN).

At that time, many years ago, SVN was the natural successor to CVS; and the new wave of tools, the distributed version control systems (DVCS), like ‘Git’ and ‘Mercurial’ were still pretty new and/or not well supported on Windows.

Several years later, again just out of interest (since my development workflow hadn’t change much), and because in the meantime the hype about all those fancy new DVCSs was in full swing, I decided to switch to one of those – but to which?

I wasn’t very attached to Subversion: My requirements were very simple and I almost exclusively used the great GUI tool TortoiseSVN, so I wasn’t angry about giving up any hard-earned Subversion commands or knowledge.

At that time, there were many open-source DVCSs available that started around the same timeframe (2003-2005) and were now, some years later, on a somewhat equal level (from my naive point of view at that time): Arch, Bazaar, Darcs, Git, Fossil, Mercurial, Monotone, to name a few.

But most of these were born on and still very much focused on the Unix/Linux world and hardly (or not even at all) useful on Windows. That also included Git, and left me with Mercurial (Hg) as the only obvious choice: It was written in Python, with multi-platform support in mind and a good reputation and documentation, as far as I could tell. There was also a nice and similar GUI frontend for it available: TortoiseHg.

So, I learned a bit about the ways of distributed version control systems in general and Mercurial in particular. But beside some initial steps, I never really used much of the command line for it, but jumped right into using TortoiseHg.

Migrating a BitBucket Mercurial project to a BitBucket Git project

The following expect a Windows system and TortoiseHg to be installed and SSH keys to be configured for BitBucket! And your local Hg repository should be up to date (push/pull/merge before, if needed).

Issues, Wikis and other BitBucket features will not be considered!
(Note: You can export issues to a zip file and import that zip file into the new BitBucket repository (overwriting all previous issues there, if any exist already).)

Step 1: Enable the Hg-Git extension in TortoiseHg

TortoiseHg -> Global Settings -> Extensions Tab -> [x] hggit -> OK.

That will also be reflected in the Hg configuration file (C:\Users\username\mercurial.ini) and looks like this:

[extensions]
hggit = 

Step 2: Backup BitBucket project

Backup the soon-to-be-converted Hg repo on BitBucket by example by renaming it in the web interface:

Project -> Settings: General: Repository details: Update repository details: Name: “Project” rename to “Project-hg” (for example).

Step 3: Create a new Git repo on BitBucket

Create a new repository on BitBucket with the now free original name “Project“ and select Git as the version control system.

Don’t create a README file.

Step 4: Convert

Go to the local working diretory of your Hg repo and do this (adjust path, URL, username and projectname accordingly):

C:\path\to\hg\proj> hg bookmark -r default master
C:\path\to\hg\proj> hg push git+ssh://git@bitbucket.org:username/projectname.git

If that push command results in an error, you should update your TortoiseHg/Mercurial installation. In my case, I got fatal error, ending with line:

genpack() got an unexpected keyword argument 'ofs_delta'

That was with TortoiseHg 4.5.3 (x64); after updating to TortoiseHg 4.9.1 (x64), all was fine.

Step 5: Modify or clone Git repo

C:\path\to\git\repos> git clone git@bitbucket.org:username/projectname.git

To modify an existing working directory instead of downloading a new clone and for other tips, see Bitbucket: Converting Hg repositories to Git.

Now

So far so good, I never had any complaints (due my simple demands, to be honest), but by now, it had become apparent that Git was the dominant tool of the trade, and I should take another look at it:

Some of the other tools mentioned before faded away, or remain in their niches; only Mercurial seems to have still a standing and is being used by Google and Facebook, as far as I know. But for this round, Git is the winner in terms of developers’ mind share.

Again, my (mental) investement in Mercurial was limited, like before with Subversion, so the switch didn’t really hurt or affect me much yet.

The one change I already noticed after swapping out the DVCS: This time, I decided to dive deeper in the understanding of Git, compared to SVN and Hg. For one thing, out of fear (I read a lot about how complicated Git would be) and also out of curiosity.

Thankfully and luckily, there is a lot of material out there, unfortunately, at the same time, one does need it and also has to weed through the good, the bad and the ugly stuff on the web. For the beginning, I sticked with the semi-official site and documentation and as usual, lot of on-demand search…


  1. A few weeks after I switched and published this post, BitBucket announced that it would stop supporting Mercurial/Hg repositories next year: Sunsetting Mercurial support in Bitbucket. [return]