gitifyhg on Pypi

gitifyhg

This git remote allows you to do local development in a git repository and push changes to an upstream mercurial repository. It does this seamlessly and allows pushing and pulling to named branches in the upstream repository.

gitifyhg does not rely on hg-git, and allows you to push and pull to and from a mercurial repository from right inside git. You do not need to adapt your git workflow in any way aside from cloning a gitifyhg url.

This is a robust and usable git to hg bridge that has been tested in production settings. It has a large test suite and better documentation than the alternatives we know about. It has been tested on several large mercurial repositories (including that of mercurial itself and the pypy repository) that break with various other git-to-hg bridge projects and is used daily in normal workflow scenarios.

That said, gitifyhg is not yet complete. Some of the features that are not fully working include:

anonymous branches are dropped, only the tip of a named branch iqs kept
remote branch and bookmark tracking is not 100% stable
pushing octopus merges is not supported
cloning mercurial branches that are subdirectories of other branches fails
cloning duplicate case sensitive names on case insensitive filesystems (mac, windows) fails

However, if you are looking for a git-svn type of workflow that allows you to clone mercurial repositories, work in local git branches, rebase those branches and push them back to mercurial, you have found it. It works. Try it.

Unfortunately, though, maintenance of gitifyhg has fallen off. You can pick it up if you like, but you may also be interested in working on the git-remote-hg script that is shipping with the main git project. We're told it's more functional than it once was and that the improvements gitifyhg once had over it have been addressed. We have not confirmed this, but it's worth checking out. Because it has support from the git developers, it's probably the best project to get behind at this time.

URLS

Dependencies

gitifyhg has been tested to run on CPython 2.6 and 2.7. Any python that supports Mercurial should be supported. Sadly, this excludes both pypy and CPython 3.

gitifyhg requires at least Mercurial 1.9, older versions are currently not supported. We perform continuous testing against various Mercurial versions ranging from 1.9 to 2.5. However, this does not completely rule out the possibility of compatibility issues, so we recommend using Mercurial 2.4.x or 2.5.x, as this is what gitifyhg is primarily developed for. Should you actually encounter any compatibility issues with any older or newer Mercurial versions, please submit an issue.

It has been tested on Arch Linux and Mac OS X. In general it should work equally well on other Unix-like operating systems like *BSD or Solaris. All bets are off with Windows, but please let us know if it works or you fixed it.

gitifyhg explicitly depends on:

These packages will be installed automatically by easy_install, pip, setup.py install, or setup.py develop.

gitifyhg also expects the following to be installed on your OS:

python2
git

Install

gitifyhg is a properly designed Python package. You can get it from pypi using either

pip install gitifyhg

easy_install gitifyhg

gitifyhg works in a virtualenv, but you're probably just as well off to install it at the system level.

You can also install gitifyhg manually with

git clone https://github.com/buchuki/gitifyhg.git
python setup.py install

If you want to hack on it, use setup.py develop, instead. In this case, you probably are better off using a virtualenv.

Instructions

gitifyhg is a git remote. Once installed, you can clone any Mercurial repo using

git clone gitifyhg::<any mercurial url>

Now run git branch -r to see the list of Mercurial branches. If it was a named branch upstream, it will be named branches/<branchname> in git. Bookmarks are referred to directly by their name. For now, we recommend only interacting with named branches.

master automatically tracks the default branch. You can check out any named mercurial branch using

git checkout --track origin/branches/<branchname>

As a standard git practice, we recommend creating your own local branch to work on. Then change to the tracked branch and git pull to get upstream changes. Rebase your working branch onto that branch before pushing

git checkout -b working_<branchname>
# hack add commit ad nauseam
git checkout branches/<branchname>
git pull
git checkout working_<branchname>
git rebase branches/<branchname>
git checkout branches/<branchname>
git merge working_<branchname>
git push

You can create new named upstream branches by giving them the branches/ prefix

git checkout -b "branches/my_new_branch"
# hack add commit
git push --set-upstream origin branches/my_new_branch

And that's really it, you just use standard git commands and the remote takes care of the details. Just be cautious of incoming anonymous branches, don't do any octopus merges and you should be set.

Caveats

Mercurial allows spaces in branch, bookmark, and tag names, while git does not. To keep git from choking if upstream has spaces in names, gitifyhg will replace them with three underscores and has the sense to convert between the two formats when pushing and pulling.

Mercurial does not support lightweight tags. Tags in mercurial that get pushed to the remote repo require an extra commit in he mercurial history. If you push a lightweight tag, then gitifyhg will set a default user, date, and commit message for you. However, if you create a heavyweight tag using git tag <tagname> --message="commit message", gitifyhg will use the commit information associated with that tag when you run git push --tags.

By default, gitifyhg ignores branches that have been closed in Mercurial. This supplies a substantial cloning speedup on large repos, and alleviates a few issues we are still working out in conflicting branch names. If you would like to clone a repository including closed branches, first set the GITIFYHG_ALLOW_CLOSED_BRANCHES environment variable.

If you have any trouble, please let us know via the issue tracker, preferably with pull requests containing test cases.

Communicating with Mercurial Users

One problem with using git to access Mercurial repos is that the sha identifiers in the two DVCSs are different. This makes it difficult to discuss or share patches on mailing lists or other mediums.

Gitifyhg alleviates this by storing Mercurial's sha1 identifiers in a git-notes ref. If you need to discuss SHA1s with upstream Mercurial users, issue the following commands:

$ ls .git/refs/notes/
hg  hg-ceda6818a39a022ef11ba5ee2d7964f57cb3accf
# note the SHA1 above and adapt the following command
git symbolic-ref refs/notes/hg refs/notes/hg-ceda6818a39a022ef11ba5ee2d7964f57cb3accf
git config core.notesRef refs/notes/hg

From now on, your git-log output will include lines that look like the following for each pulled ref:

Notes (hg):
  e6eabc9d7e24f55e829d0848380f6645e57f4b6a

That is the Mercurial SHA1 identifier of the commit in question; you can paste that into an e-mail or chat message to discuss a specific commit with other users.

If somebody else mentions a commit by it's hg SHA1 identifier, you can search for that commit in git using:

git log --grep=<HGSHA1>

Development

You can hack on gitifyhg by forking the github repository. All the code is in the gitifyhg.py file, and tests are in the test directory.

We recommend developing in a virtualenv

cd gitifyhg
virtualenv -p python2.7 venv
. venv/bin/activate
python setup.py develop

There is currently a problem where if you have a development version of gitifyhg in an active virtualenv and a stable version installed at the system level, git will pick the system level gitifyhg regardless of the PATH setting in the virtualenv. The only workaround I have found is to temporarily uninstall the system version.

If you want debugging information out of gitifyhg, set the DEBUG_GITIFYHG=on environment variable. This is done automatically if you are running the test suite.

The gitifyhg remote is called by git and commands are passed on stdin. Output is sent to stdout. The protocol is described at https://www.kernel.org/pub/software/scm/git/docs/git-remote-helpers.html The git remote prints INPUT and OUTPUT lines for each of these to help introspect the protocol.

We expect pep8 compliance on contributions. If possible, enable highlighting of pep8 violations in your editor before committing.

The gitifyhg mailing list is hosted on Google groups, but we prefer the issue tracker for most development and decision-making related discussions.

Testing

Tests are continuously run by Travis-CI:

Note that testing has recently changed. We used to use py.test and tox to run our tests. We've recently switched to sharness both because it's easier to test command-line tools with and because it is the same infrastructure used by git itself.

To test with sharness, simply cd test and run make. You can run individual test files with ./test-name.t.