== What it does ==

'git-remote-hg' is the semi-official Mercurial bridge from Git project, once installed, it allows you to clone, fetch and push to and from Mercurial repositories as if they were Git ones:

git clone "hg::http://selenic.com/repo/hello"

== Requirements ==

To use this tool under Unix-based operating systems like Linux, Mac OS X, *BSD, etc., first make sure that you have Python 2.6 or later, and Mercurial installed.

Then download the 'git-remote-hg' script, put it anywhere in your $PATH and make sure it is executable, e.g. using curl:

curl -o ~/bin/git-remote-hg https://raw.githubusercontent.com/fingolfin/git-remote-hg/master/git-remote-hg chmod +x ~/bin/git-remote-hg

If your system does not have curl, but wget, you can use this command:

wget https://raw.github.com/fingolfin/git-remote-hg/master/git-remote-hg -O ~/bin/git-remote-hg chmod +x ~/bin/git-remote-hg

That's it. :)

== Configuration ==

If you want to see Mercurial revisions as Git commit notes:

% git config core.notesRef refs/notes/hg

If you are not interested in Mercurial permanent and global branches (aka. commit labels):

% git config --global remote-hg.track-branches false

With this configuration, the 'branches/foo' refs won't appear.

If you want the equivalent of 'hg clone --insecure':

% git config --global remote-hg.insecure true

If you want 'git-remote-hg' to be compatible with 'hg-git', and generate exactly the same commits:

% git config --global remote-hg.hg-git-compat true

== Notes ==

Remember to run git gc --aggressive after cloning a repository, specially if it's a big one. Otherwise lots of space will be wasted.

The oldest version of mercurial supported is 1.9. For the most part 1.8 works, but you might experience some issues.

=== Pushing branches ===

To push a branch, you need to use the "branches/" prefix:

% git checkout branches/next

do stuff

% git push origin branches/next

All the pushed commits will receive the "next" Mercurial named branch.

Note: Make sure you don't have +remote-hg.track-branches+ disabled.

=== Cloning HTTPS ===

The simplest way is to specify the user and password in the URL:

git clone hg::https://user:[email protected]/user/repo

You can also use the http://mercurial.selenic.com/wiki/SchemesExtension[schemes extension]:

[auth] bb.prefix = https://bitbucket.org/user/ bb.username = user bb.password = password

Finally, you can also use the https://pypi.python.org/pypi/mercurial_keyring[keyring extension].

However, some of these features require very new versions of 'git-remote-hg', so you might have better luck simply specifying the username and password in the URL.

=== Caveats ===

The only major incompatibility is that Git octopus merges (a merge with more than two parents) are not supported.

Mercurial branches and bookmarks have some limitations of Git branches: you can't have both 'dev/feature' and 'dev' (as Git uses files and directories to store them).

Multiple anonymous heads (which are useless anyway) are not supported; you would only see the latest head.

Closed branches are not supported; they are not shown and you can't close or reopen. Additionally in certain rare situations a synchronization issue can occur (https://github.com/felipec/git/issues/65[Bug #65]).

Limitations of the remote-helpers' framework apply. In particular, these commands don't work:

• git push origin :branch-to-delete
• git push origin old:new (it will push 'old') (patches available)
• git push --dry-run origin branch (it will push) (patches available)

== Other projects ==

There are other 'git-remote-hg' projects out there, do not confuse this one, this is the one distributed officially by the Git project:

• https://github.com/msysgit/msysgit/wiki/Guide-to-git-remote-hg[msysgit's git-remote-hg]
• https://github.com/rfk/git-remote-hg[rfk's git-remote-hg]

For a comparison between these and other projects go https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives[here].

== Contributing ==

If you spot a bug and know how to fix it, or have some other improvements, please consider submitting a https://github.com/fingolfin/git-remote-hg/pulls[pull request].