Thursday, March 29, 2012

hg-git and TortoiseHg

[UPDATE 2013-05-28] Make sure your hg-git is up to date and pointing at the most recent tag. I have had issues when I have updated hg but not pulled the latest hg-git changes from durin42.

If for some reason you were using Mercurial, aka Hg, and you needed to interact with Git, then you probably have heard about hg-git. There are other tools, but I think this one is the oldest, and even though not necessarily the best, it works fine. Now if you are on Windows, then you are most likely using TortoiseHg, aka thg, and if so integrating hg-git is a snap. The only confusion is that there are multiple website with seemingly different information. If you already have TortoiseHg installed, all you have to do is follow the directions in the TortoiseHg v2.1.1 Documentation: Section 9.3: Use with other VCS systems: hg-git (git). There are some key differences between this documentation and what you will find on various other websites which are geared toward non-TortoiseHg users. In particular, hg-git requires Dulwich, a python-git implementation, but note what it says in the thg docs:

Current versions of TortoiseHg include dulwich version 0.7.0. We recommend to use hg-git version 0.2.6 with this version of dulwich and Mercurial 1.8.

So you don't need to install Dulwich if you are using hg-git with TortoiseHg! This is intended for non-thg users.

Now on to use:

Make sure that you have enabled the plugin by adding the [extension] line hggit = C:\hg-git\hggit to your mercurial.ini file, which can be found in your user-profile folder (the one with your Windows user name). This is described in all of the websites, but most of them use the Linux/Unix home folder ~/.hgrc which you will NOT find on a windows machine unless you are using Cygwin or minGW/MSYS. For thg installations of Mercurial, the %USERPROFILE%\mercurial.ini file is the equivalent of the Linux ~/.hgrc file.

Branches should to bookmarked before you can push them to a git repo. Basically this is how hg-git deals with branches. A Git branch is the equivalent of an hg bookmark. This is because branches in Mercurial and Git are different. You can do this manually by issuing the command hg bookmark -r default master. That basically maps the hg branch called default to the git branch called master, by creating an hg bookmark also called master. The -r allows you to specify the revision (could be an hg branch, bookmark or tag), instead of pointing to the current working copy. For example if you have an hg branch named x64 if you want to push it to a Git repo, make a bookmark, hg bookmark -r x64 x64_git; note that in Mercurial branches and bookmarks cannot have the same name. There is an hg-git extension you can add that will remove the suffix, but a better practice might be to use bookmarks instead of named branches in Mercurial.

Finally to push to your git repo use hg push git+ssh://git@github/user/repo. Note that protocol "git+ssh://" and the switch from colon to slash between github and user! That tells hg-git to push to a git repo using ssh. Also you will need to enable Pageant, you can find it in the thg folder in program files. You will need an ssh key. If you don't already have one, you can download puttygen and follow the directions on Bitbucket: Using the SSH protocol.

That's it. You don't need to enable the bookmarks extension, because it became part of Mercurial core 1.8. There is an issue with author, you want to make sure that you are commiting with the same username. You can set that in either mercurial.ini globally or in .hg/hgrc per repo. Alternately select thg settings and commit. But not setting this is NOT a show stopper.