Skip to content

Hg-Git Mercurial Plugin

We hear from a number of people who are using Mercurial for their projects but want to host them on GitHub because they want their project to benefit from the…


We hear from a number of people who are using Mercurial for their projects but want to host them on GitHub because they want their project to benefit from the community here. Or perhaps they are in a group where some of the developers want to use Mercurial and others want to use Git and so they just stick with Subversion (ugh). We don’t want to live in a world where developers who are ready to switch to a DVCS end up staying with Subversion.

So, I’ve been working on a plugin for Mercurial that lets it communicate with a Git server as a native Git client. I give you hg-git!

This means that if you are a Mercurial developer you can install this plugin and then push and pull to and from Git servers, either GitHub or somewhere else. It is a lossless bi-directional bridge, meaning you can push to a Git server from one Hg user, then another Hg user can clone using this plugin and the node ids will all be identical. It can even handle things like tags, explicit renames, named branches, octopus merges and more.

The plugin is pretty far along at this point – I’ve been using it for all the hg-git development and I’ve heard from a number of others who are using it successfully even on relatively large projects. It is slow sometimes and may not handle some edge cases well, but the software is rapidly maturing. If you do use it, please let me know about any issues you run into, we want to make this rock solid.

There are no external dependencies – the library is entirely written in python and contains a pure python implementation of all the Git functionality it needs, so you don’t need to have Git installed locally at all. It has been known to work with Mercurial 1.1 and 1.2 – let me know if you try it with something else.


From Hg with the plugin installed, you can clone a Git repository like this:

$ hg clone git://

Or, if you have an existing Hg repository, you can run something like this:

$ cd myproject # (an Hg repository)
$ hg gremote add origin git(at)
$ hg gpush

With those two commands you can basically import your Hg repository into a GitHub repository. Then people can fork and work on your code in Hg or in Git and push back up, then you can pull in any contributed work with something like this:

$ hg gremote add scott git://
$ hg gfetch scott
$ hg update

The basic commands the plugin adds to the Hg command library are ‘gclone’, ‘gremote’, ‘gpush’ and ‘gfetch’ – all roughly equivalent to their Git counterparts. Also, running a normal ‘hg clone’ with an identifiable Git protocol (git://, git+ssh://) will fire up ‘gclone’ automatically.

See the hg-git homepage for more information.

Explore more from GitHub



The latest on GitHub, from GitHub.
GitHub Universe 2024

GitHub Universe 2024

Get tickets to the 10th anniversary of our global developer event on AI, DevEx, and security.
GitHub Copilot

GitHub Copilot

Don't fly solo. Try 30 days for free.
Work at GitHub!

Work at GitHub!

Check out our current job openings.