Nerd Corner: Convert a Mercurial (Hg) repo to Git, with full fidelity, on any OS

Fortunately or unfortunately, Git won over Mercurial. I placed a few bets on Mercurial at the time, so I have a bit of a tail of repositories left to convert.

Converting on Windows with full fidelity isn’t really possible. None of the scripts work well, and the case insensitive file system can cause issues. Luckily, Windows Azure makes it super easy to borrow a small Linux instance quickly.

I’ve documented what I do in this post. Anybody with a web browser can follow these steps, on any platform. There looks like a lot of steps, but that’s just because I’m spelling out every last detail for clarity.

Create a Linux VM in Windows Azure

  1. Sign in to
  2. Create a new VM from the gallery:
    Create VM from Gallery
  3. Choose an Ubuntu release. As of this post, I chose Ubuntu Server 13.10.
  4. Name the VM anything you want
  5. Untick “Upload compatible SSH key for authentication”, unless you know what you’re doing there
  6. Tick “Provide a password”
  7. Leave all the rest of the defaults, and just keep clicking Next
  8. Wait a moment for the VM to get provisioned

Connect to the VM

For this, we’ll just be connecting to a command line via SSH: no GUIs will be harmed.

Because SSH is so prevalent, there are tool chains available for every platform. I’m actually writing this post on my Surface RT (not Pro), using an app called SSH-RT from the Windows Store.

  1. Connect to the DNS name for your new VM (mine was
  2. Use the username and password you established during the wizard
  3. You should now be at a command line like azureuser@git-convert:~$

Install Git and Hg on the VM

Ubuntu doesn’t ship with Git or Mercurial installed by default, but it does have an awesome package manager called apt-get.

  1. Run sudo apt-get install git
  2. Run sudo apt-get install mercurial

The sudo prefix is a command to elevate your permissions, kind of like a UAC prompt on Windows.

Clone hg-fast-export on to the VM

We’ll be using a tool called hg-fast-export to convert the Mercurial repository to Git, without having to replay each individual changeset like some tools do. This tool is in a Git repo, so we’ll just clone that repository down in order to get it onto the VM.

  1. Run git clone

Clone your Mercurial repository on to the VM

For the sake of simplicity, we’re just going to use HTTPS instead of SSH.

  1. Run hg clone https://your/hg/repo/address

Export your Mercurial repository to a new Git one

  1. Create a new folder for your Git repository: mkdir your-repo-git
  2. Change to that folder: cd your-repo-git
  3. Initialize an empty Git repository there: git init
  4. Do the fast export: ../fast-export/ -r ../your-repo/

Upload your Git repository to your Git hosting

  1. Add the remote: git remote add origin https://your/git/repo/address
  2. Push up all branches and tags: git push -u origin --all

Convert Hg-specifc config to Git

Take the opportunity now to convert your .hgignore file to an equivalent .gitignore one. You can go and do this back on your own machine.

Delete the VM

Back in the Azure Management Console, delete the VM. When you do this, choose to “delete the attached disks”. (It will ask you.)

All done!

You’re all done. Wasn’t that just a perfect, easy use of the cloud?