Converting Mercurial Repositories to Git on Windows

If you work with text, you need version control. That rule applies regardless of whether you write code or poetry (some might argue that those two are the same, anyway). Ignoring the CVS and SVN dinosaurs two distributed version control systems are being regarded as state of the art: Git and Mercurial. Functionality-wise they are nearly identical, but it seems that Git, with its open source background, is poised to take over the enterprise, too, where Mercurial used to be strongest.

For Starters

If you are just getting started with version control, take a look at the excellent SourceTree client software, and consider one of the popular hosting services Bitbucket, Github or Visual Studio Online, each of which have very usable free plans (although it should be mentioned that Github offers private repositories only for paid accounts).


If have have been using version control for some time you might have a number of Mercurial repositories that you want to convert to Git. The remainder of this article explains how to do that on Windows.

This guide assumes you have TortoiseHg and Git installed. When installing Git make sure to select the option Use Git from the Windows Command Prompt as shown in the following screenshot. No other software is required.

2015-06-01 01_40_42-Git Setup


Edit your mercurial configuration file (located in %Userprofile%\mercurial.ini), adding the following lines:

hggit = 
hgext.bookmarks =
intree = True

This enables the hg-git extension and instructs it to create .git repository directories next to .hg repository directories instead of putting them in subdirectories named git.

On the command line, make sure hg-git is enabled correctly by running:

hg help hggit

It should print something like this:

hggit extension - push and pull from a Git server
This extension lets you communicate (push and pull) with a Git server. This
way you can use Git hosting for your project or collaborate with a project
that is in Git.  A bridger of worlds, this plugin be.
Try hg clone git:// or hg clone git+ssh://
For more information and instructions, see "hg help git"
list of commands:
 gclear        clear out the Git cached data
 gexport       export commits from Mercurial to Git
 gimport       import commits from Git to Mercurial
 git-cleanup   clean up Git commit map after history editing
 gverify       verify that a Mercurial rev matches the corresponding Git rev
(use "hg help -v hggit" to show built-in aliases and global options)

Converting a Mercurial Repository to Git

On the command line, navigate to the mercurial repository you want to convert. This is the directory that contains the .hg subdirectory.

Run the following command to make a bookmark of master for default, so a reference gets created:

hg bookmark -r default master

Run the following command to create the .git repository directory:

hg gexport --debug

Starting Over

If you made a mistake or forgot something and want to start over simply delete the .git subdirectory and run:

hg gclear

Git: Turning a Bare into a Working Repository

You now have a bare Git repository in addition to the existing Mercurial repository. Turn the bare into a working repository by running:

git config --bool core.bare false

Create the index (otherwise, Git believes everything has been deleted, since a bare .git repository doesn’t include a file index):

git reset HEAD -- .

Your local source directory now contains both a Mercurial and a Git repository:

Git and Hg

That is not exactly what they tell you in coding school, but – it works!

You can push the new local Git repository to a remote hosting service like Bitbucket or Visual Studio Online comfortably with Atlassian’s SourceTree client.

You might also want to convert existing .hgignore files to .gitignore files. Unfortunately they are not fully compatible, as .gitignore does not support regular expressions.

, ,

11 Responses to Converting Mercurial Repositories to Git on Windows

  1. Dan Hook December 4, 2015 at 18:22 #

    Thanks! This was very helpful!

  2. Patrick Dezenzio December 15, 2015 at 18:22 #

    I need a little clarification. Where I work, we have a default project with multiple branches. Do I do this conversion for the default and then for each branch? Each one of these has their own folder structure complete with an .hg folder. Some guys here think one conversion is enough to pull in all branches.

    • Deepan September 1, 2016 at 03:01 #

      Yes clarification need on this. Please let us know whether only the master will be converted or all the branches and tags?

  3. Clay Nichols August 23, 2016 at 20:15 #

    How do I get rid of the former .hg repository when finished?
    Do I just delete the .hg folder?

    • Helge Klein August 28, 2016 at 20:50 #

      Yes, you can simply delete the .hg directory once you do not need it any more.

  4. devuxer May 30, 2017 at 17:19 #

    Sorry, I know this is an old post, but when I issue the commend git reset HEAD — ., I get this error:
    fatal: Could not parse object ‘HEAD`.

    Any advice on how I might solve this? Thx.

    • devuxer May 30, 2017 at 17:49 #

      Ahh, solved my own problem. I needed to use hg gclear because this was my second time trying this process for this particular repo. I had thought I just needed to delete the .git folder, but this didn’t reset things on the hg side.

  5. David August 3, 2017 at 16:17 #

    I”m wanting to import the hg repository as a sub directory in an existing git repository, can you give any guidance on this?

  6. Ahamed Shakir March 12, 2018 at 13:36 #

    Thanks, Superb post everything fine but I need to retrieve all the tags from old repository to git how can I??

  7. Ahamed Shakir March 15, 2018 at 07:55 #

    Thanks a lot, this article help me lot…. good one

  8. KWs February 18, 2019 at 09:22 #

    This has worked for me locally but when it try to do push i get an error, i hose my code on BitComet, seems like on bitbucket it’s still mercurial repo but locally it’s git so when i try to do push it conflicts. Is there anything i need to do to convert it to git on remote ?

Leave a Reply