Hg-Git Mercurial Plugin

Homepage:

https://wiki.mercurial-scm.org/HgGit

Repository:

https://foss.heptapod.net/mercurial/hg-git

Old homepage, no longer maintained:

https://hg-git.github.io/

Discussion:

[email protected] (Google Group) and #hg-git:matrix.org

This is the Hg-Git plugin for Mercurial, adding the ability to push and pull to/from a Git server repository from Hg. This means you can collaborate on Git based projects from Hg, or use a Git server as a collaboration point for a team with developers using both Git and Hg.

The Hg-Git plugin can convert commits/changesets losslessly from one system to another, so you can push via a Mercurial repository and another Hg client can pull it and their changeset node ids will be identical - Mercurial data does not get lost in translation. It is intended that Hg users may wish to use this to collaborate even if no Git users are involved in the project, and it may even provide some advantages if you're using Bookmarks (see below).

Dependencies

This plugin is implemented entirely in Python — there are no Git binary dependencies, and you do not need to have Git installed on your system. The only dependencies are:

• Mercurial 6.6
• Dulwich 0.21.6
• Python 3.8

Please note that these are the earliest versions known to work; later versions generally work better.

Installing

We recommend installing the plugin using your a package manager, such as pip:

python -m pip install hg-git

Alternatively, you can clone this repository somewhere and install it from the directory:

hg clone https://foss.heptapod.net/mercurial/hg-git/
cd hg-git
python -m pip install .

And enable it from somewhere in your $PYTHONPATH:

[extensions]
hggit =

Contributing

The primary development location for Hg-Git is Heptapod, and you can follow their guide on how to contribute patches.

Alternatively, you can follow the guide on how to contribute to Mercurial itself, and send patches to the list.

Usage

You can clone a Git repository from Mercurial by running hg clone <url> [dest]. For example, if you were to run:

$ hg clone git://github.com/hg-git/hg-git.git

Hg-Git would clone the repository and convert it to a Mercurial repository for you. Other protocols are also supported, see hg help git for details.

If you are starting from an existing Mercurial repository, you have to set up a Git repository somewhere that you have push access to, add a path entry for it in your .hg/hgrc file, and then run hg push [name] from within your repository. For example:

$ cd hg-git # (a Mercurial repository)
$ # edit .hg/hgrc and add the target git url in the paths section
$ hg push

This will convert all your Mercurial data into Git objects and push them to the Git server.

Now that you have a Mercurial repository that can push/pull to/from a Git repository, you can fetch updates with hg pull:

$ hg pull

That will pull down any commits that have been pushed to the server in the meantime and give you a new head that you can merge in.

Hg-Git pushes your bookmarks up to the Git server as branches and will pull Git branches down and set them up as bookmarks.

Hg-Git can also be used to convert a Mercurial repository to Git. You can use a local repository or a remote repository accessed via SSH, HTTP or HTTPS. Use the following commands to convert the repository, it assumes you're running this in $HOME:

$ mkdir git-repo; cd git-repo; git init; cd ..
$ cd hg-repo
$ hg bookmarks hg
$ hg push ../git-repo

The hg bookmark is necessary to prevent problems as otherwise hg-git pushes to the currently checked out branch, confusing Git. The snippet above will create a branch named hg in the Git repository. To get the changes in master use the following command (only necessary in the first run, later just use git merge or git rebase).

$ cd git-repo
$ git checkout -b master hg

To import new changesets into the Git repository just rerun the hg push command and then use git merge or git rebase in your Git repository.

.gitignore and .hgignore

If present, .gitignore will be taken into account provided that there is no .hgignore. In the latter case, the rules from .hgignore apply, regardless of what .gitignore prescribes.

Please note that Mercurial doesn't support exclusion patterns, so any .gitignore pattern starting with ! will trigger a warning.

This has been so since version 0.5.0, released in 2013.

Further reading

See hg help -e hggit and hg help hggit-config.

Alternatives

Since version 5.4, Mercurial includes an extension called git. It interacts with a Git repository directly, avoiding the intermediate conversion. This has certain advantages:

• Each commit only has one node ID, which is the Git hash.
• Data is stored only once, so the on-disk footprint is much lower.

The extension has certain drawbacks, however:

• It cannot handle all Git repositories. In particular, it cannot handle octopus merges, i.e. merge commits with more than two parents. If any such commit is included in the history, conversion will fail.
• You cannot interact with Mercurial repositories.

Another extension packaged with Mercurial, the convert extension, also has Git support.

Other alternatives exist for Git users wanting to access Mercurial repositories, such as git-remote-hg.