Using GitHub with Mercurial and TortoiseHG

Introduction

I don't think there's a single developer who doesn't know GitHub, the popular source-control web hosting service for Git. If I'm wrong and you never head about it I strongly suggest you to fill this huge gap by reading (at least) the GitHub and Git wikipedia pages. Taking a look to the github.com and git-scm.com official site won't hurt either.

If you know what I'm talking about, keep reading: you're most certainly aware that in order to use the GitHub service you need to adopt Git, which is not only the most used source-control manager (SCM from now on) of the current decade, yet also a very brilliant and innovative piece of work due to its distribuited, versatile and elegant approach. These - togheter with the GitHub project itself- are the reasons why it gradually crushed the competitors, including some very praised open-source industry standards such as CVS and SVN - which were based on a traditional, less-modern centralized SCM paradigm.

While Git is widely adopted by either Windows and Linux developer communities, the latter certainly is its true love source - after all it was developed by a certain Linus Torvalds. Conversely, it's still slightly less popular between Windows users for the following reasons:

• a late win32 porting of the most used UI  - msysgit e TortoiseGit among others - which tend to be preferred by most Windows developers who tend to despise a bare command-line interface.
• the almost-simultaneos diffusion of Mercurial (formerly HG), another distribuited SCM featuring tools and settings as neat as Git ones, with a generally better support for Windows platforms, software and developer frameworks.

Another strong reason which favored Mercurial over Git on windows platforms was, in 2008, the launch of the bitbucket.org website, entirely based on Mercurial (until 2011, when Git was adopted too) and very similar to GitHub in almost any way.

I don't want to go further than that, let alone saying which SCM would be better and why: in my personal opinion, being an enthusiast of both Git and Mercurial, I think that they are two amazing products which - despite their slightly different architectural approach - are equally able to perfectly fullfill almost any modern developing scenario. To put it in other words, I don't think I ever missed one of them while working with the other one.

If you're looking for a deeper analysis of the similarities and the differences between Git e Mercurial I strongly suggest you to start by reading these two excellent (despite their age) posts. The first one is practical, technical and analytic, whilst the latter is more theoretical and fun: just pick the one you feel most suited for your style, just like you'll often end up choosing your SCM.

• DVCS Analysis: Git and Mercurial (by Google tech)
• Git vs Mercurial: Please Relax

Interoperability between Mercurial and Git by using TortoiseHG

Let's bring the main topic back: how to effectively use GitHub site & services with Mercurial instead of Git. The first question you could ask is: does it even make any sense? Why would we want to use a Git-related web host if we don't feel like adopting Git? Why don't just use BitBucket instead?

Personally I never had to answer such a question for a long while - until a customer asked me to put his project repository on GitHub. A huge, widely distribuited, Mercurial-based repository. Needless to say, changing SCM on-the-fly was not an option - we wouldn't want to lose the history, let alone re-configuring each and every developer client. Neither we could add a second repository: it would have meant duplicating the burden of the aforementioned clients.

Luckily for me, I found a neat native plugin of the Mercurial GUI suite I was using - TortoiseHG, which is also one of the most widely known and used on Windows platforms - who was able to do exactly what I needed: creating an interop bridge between Mercurial commands and any existing Git repository. The plugin name is hggit and it's included in the TortoiseHG default package: it can be activated with a single click via he Extensions panel:

Once you have it activated, you can easily access any Git repository - including those created on the GitHub web site: it's as simple as that. You just have to learn how to properly do that.

Create and mantain a GitHub project

Let's see how we can effectively sinchronize a local Mercurial repository on our HDD with a remote Git repository hosted on GitHub without using Git.

The first thing we need to do is to create the repository - assuming it doesn't exist yet: if that's not the case, just skip this step and go further.

Don't forget to also issue a first commit in order to add some files to the local repository. Once you did that, you'll end up with a repository you can export on GitHub. Point your browser to the github.com website, login using your credential and, if needed, create a new GitHub repository:

Fill up the form that will open with all the required fields: choose a suitable name for the repository and set it as public or private depending on your specific needs:

Avoid to create any README, gitignore or license file for now... You will be able to add them later using your local repository, just as any other file. Click to the Create repository button and you will be able to face your new (empty) project:

Cut and past the relevant URL ( https://github.com/Darkseal/my.hggit.project.git  in my example) and add the  git+ prefix at the start, just like the following:

The  git+ prefix is crucial here: it's the one that tells the hggit plugin to perform all the interop bridge operations between Mercurial and the remote Git repository.

Paste the hereby modified URL into the TortoiseHG remote repository interface, accessible thru the Synchronize... option in the contextual menu of the root repository folder on your HDD drive:

Give it a friendly name (GitHub seems appropriate here), then click on Save: after you did that you can push your local (Mercurial) repository to the (Git) remote one using the appropriate icon on that same window. The GUI will prompt you for an username and a password to let you access the remote repository - just use your GitHub credentials. Notice that you'll have to write them two consecutive times: this might seems rather odd but it's actually required by the bridge created by the hggit plugin.

As soon as the push ends your project will be available as the master branch of your GitHub repository:

You did it! Well done.

Conclusions

The most experienced GitHub users would definitely like to know if the above method could be used to manage additional branches - such as the gh-pages branch, used by GitHub to create and mantain the project web pages (you don't know them? click here for more info). The answer is: yes, it can! You will be able to do that by using the Mercurial bookmark, which are the Mercurial counterpart of Git branches and are used as such by the hggit plugin. I will extensively talk about that in an upcoming post.

The sample project created for this article is publicly available on GitHub (where else?) at this URL address.

Happy coding!

Print Friendly & PDF Download