Create a Git Mirror

posted by Steve Losh on November 9, 2009

Of all the distributed revision control systems like Mercurial, git is probably the most popular. If you use Mercurial for a project you can quickly and easily make a git mirror of your project so that git users can contribute!

Install hg-git

First, you’ll need to download the hg-git plugin:

easy_install dulwich
hg clone http://bitbucket.org/durin42/hg-git/

Now edit your ~/.hgrc file to contain:

[extensions]
hggit = /path/to/hg-git

Create a GitHub Account

You’ll need a place to put your git mirror, and GitHub is perfect for that. Go ahead and sign up for a GitHub account if you don’t already have one.

Create a Repository on GitHub

Now that you have a GitHub account, you’ll need to create a repository with the “New Repository” button.

Once you create a new repository, you’ll be looking at a page that looks like this:

GitHub New Repo Sample

See the git@github.com:username/project.git URL? Remember that, because that’s what you’ll need to use when you push your mirror.

Push Your Project

Now that you’ve installed hg-git and created a repository for your project on GitHub, you need to push your Mercurial repository to GitHub. First, add the git URL to your Mercurial repository by editing the .hg/hgrc file in your project to contain:

[paths]
git = git+ssh://git@github.com/username/project.git

IMPORTANT NOTE: You will need to replace the : after github.com with a / (forward slash). This is necessary because of how Mercurial handles repository paths!

You’ll also need to replace username and project with the appropriate values, of course.

Now you just need to push to the git path to create your mirror:

hg push git

This will take a few seconds, especially if you have a big repository. Once it finishes you’ll have a 100% functional git mirror at http://github.com/username/project/. Git users can clone your project by running git clone git://github.com/username/project.git and might never even realize that you use Mercurial.

Accepting Contributions

Creating a mirror for git users to clone is very nice, but eventually (if your project is at all interesting) someone is going to send you a pull request on GitHub.

hg-git makes it easy to deal with contributions from git users. First, add the contributor’s fork to your projects’ paths:

[paths]
git = git+ssh://git@github.com/username/project.git
contributor = git+ssh://git@github.com/contributor_username/project.git

Again, make sure you replace the : after github.com with a / (forward slash)!

Then pull their changes into your Mercurial repository:

hg pull contributor

You can use graphlog to see exactly what your repository looks like at this point (and if you need to merge).

Merge if you need (and/or want) to merge, and then push their contributions to your main Mercurial repository and your git mirror:

hg push
hg push git

That covers the basics! Things can get more complicated if you’ve got a heavily branching workflow, but this tip should get your on your way to accepting patches from git users.

You’ve chosen Mercurial, but lots of other people prefer git. Make it easy for them to contribute to your project.