Git interoperability with a Mercurial Repository

In the vast landscape of version control systems, Git has emerged as a dominant force, widely adopted for its distributed nature, robust branching model, and expansive ecosystem. However, many organizations still rely on Mercurial repositories, a powerful distributed version control system in its own right, often due to historical reasons or specific project needs. The challenge arises when teams need to collaborate or migrate, requiring seamless Git interoperability with a Mercurial repository. Bridging this gap is crucial for maintaining productivity, facilitating collaboration across diverse teams, and enabling smooth transitions when moving between systems. This article delves into the practical aspects of achieving this interoperability, exploring the tools and techniques that allow developers to work with both systems without friction, ensuring that valuable project history and workflows remain intact.

Understanding the Need for Interoperability

The co-existence of Git and Mercurial within an organization, or even across collaborating partners, is not uncommon. While both are Distributed Version Control Systems (DVCS), they have distinct architectural philosophies and command sets. Git’s popularity, fueled by platforms like GitHub and GitLab, often leads to a desire to leverage its advanced features and large community. Conversely, Mercurial’s perceived simplicity and often more predictable behavior have kept it a preferred choice for some. The primary need for interoperability stems from scenarios such as phased migrations, where not all projects can switch simultaneously, or cross-team collaboration where each team has its preferred DVCS.

Without effective interoperability, teams face significant hurdles. Developers might be forced to context-switch between different command sets, leading to errors and reduced efficiency. Data integrity can also be jeopardized if changes are manually ported or if repository history is lost during clumsy conversion attempts. Furthermore, the ability to selectively push or pull changes between Git and Mercurial repositories enables a hybrid workflow, allowing teams to leverage the strengths of both systems rather than being forced into an all-or-nothing migration. This flexibility is vital for complex, long-running projects or when integrating with external vendors using a different VCS.

For instance, a software company might have legacy projects maintained in Mercurial, while all new development starts in Git. Enabling Git interoperability with a Mercurial repository allows developers to contribute to older projects using their familiar Git tools, or even to port specific features from a Mercurial codebase into a new Git-based one without a full-scale, disruptive migration. This pragmatic approach minimizes risk and maximizes developer comfort and efficiency.

Key Tools for Bridging the Gap: hg-git

The most widely recognized and robust solution for enabling Git interoperability with a Mercurial repository is the hg-git extension. This powerful tool allows a Mercurial repository to interact with a Git repository as if it were another Mercurial remote. It translates Git objects (commits, trees, blobs) into Mercurial changesets and vice-versa, providing a seamless bridge between the two DVCS. Installing and configuring hg-git is generally straightforward, making it an accessible option for most users.

Once installed, hg-git allows users to clone Git repositories using Mercurial, push Mercurial changes to a Git remote, and pull Git changes into a Mercurial repository. This bidirectional capability is what makes it so valuable for ongoing collaboration. It handles the complexities of mapping Git’s SHA-1 hashes to Mercurial’s changeset IDs, and Git’s branches and tags to Mercurial’s bookmarks and tags. While powerful, it’s important to understand that some advanced features or concepts might not translate perfectly due to the inherent differences in the two systems’ data models. For example, Git’s lightweight branches versus Mercurial’s named branches require careful handling, often relying on Mercurial’s “bookmarks” feature for Git-like branch tracking.

hg-git is particularly useful for teams that need to maintain active development in both environments or for individuals who prefer Git but must interact with Mercurial projects. It allows developers to largely stay within their preferred command-line interface or GUI, abstracting away the underlying differences. This significantly reduces the learning curve and potential for errors that would arise from manual conversions or constantly switching between two distinct sets of commands. It’s an essential tool for any organization navigating a hybrid VCS environment.

Setting Up hg-git for Interoperability

To begin leveraging hg-git, you first need to install it. It’s typically available via package managers or can be installed directly from PyPI. Once installed, you must enable the extension in your Mercurial configuration file (~/.hgrc or .hg/hgrc for a specific repository). This simple step unlocks the cross-VCS capabilities.

1. Install hg-git: Use pip install hg-git or your system’s package manager. Ensure you have Mercurial and Git installed and accessible in your PATH.
2. Enable the Extension: Open your Mercurial configuration file (~/.hgrc on Linux/macOS, or %USERPROFILE%\mercurial.ini on Windows). Add the following lines under a [extensions] section: ``` [extensions] hgext.git =

   
    This tells Mercurial to load the `hg-git` extension.
   

3. Clone a Git Repository: From your terminal, use the familiar Mercurial clone command but specify a Git URL: ``` hg clone git://github.com/user/repo.git my-repo

   
    Mercurial will then pull the Git repository's history and translate it into a Mercurial repository on your local machine.
   

4. Push to a Git Remote: To push your Mercurial changes to a Git repository, you can add the Git remote URL to your Mercurial repository’s .hg/hgrc file under the [paths] section: ``` [paths] default = ssh://git@github.com/user/repo.git

   
    Then, use `hg push` as you normally would. `hg-git` will handle the translation and push to the Git remote.
   

5. Pull from a Git Remote: Similarly, to pull changes from a Git repository into your Mercurial project, use hg pull. Ensure your [paths] configuration points to the Git remote.

It’s important to note that while hg-git generally handles common operations well, complex Git workflows involving rebase, squashing, or intricate branch merging might require a deeper understanding of how these operations translate, or might be best performed directly in the native Git repository if possible. For daily commit, push, and pull operations, however, it performs admirably.

Migration Strategies: When Interoperability Becomes Conversion

While Git interoperability with a Mercurial repository is excellent for ongoing collaboration, there are times when a full, one-time migration from Mercurial to Git is necessary. This typically happens when an organization decides to standardize on Git entirely, aiming to decommission its Mercurial infrastructure. The goal here is not just to synchronize changes, but to convert the entire project history, including all branches, tags, and commits, into a new Git repository.

The hg-git extension can also facilitate this full migration process by allowing a Mercurial repository to be cloned as a Git repository, effectively converting its history. Another popular tool for this purpose is git-fast-export, which can import Mercurial history exported in a Question & Answer :

I use GIT on a Mac. Enough said. I have the tools, I have the experience. And I want to continue to use it. No wars here…

The problem is always with interoperability. Most people use SVN, which is great for me. Git SVN works out of the box, and is a no frills solution. People can continue happily use SVN and I don’t lose my workflow and neither my tools.

Now… Some guys come along with Mercurial. Fine for them: they have their reasons. But I can’t find any GIT HG out-of-the-box. I don’t want to switch to HG, but I still need to interoperate with their repository.

Any of you guys know a simple solution for this?

There’s a new git-remote-hg tool that provides native support:

Bridge support in Git for Mercurial and Bazaar.

Just copy git-remote-hg to your $PATH, make it executable, and that’s it, no dependencies (other than Mercurial):

git clone hg::https://www.mercurial-scm.org/repo/hg/ 

You should be able to push and pull from it as if it was a native Git repository.

When you push new Git branches, Mercurial bookmarks will be created for them.

See the git-remote-hg wiki for more information.