git-remote-hg(1)
================

NAME
----
git-remote-hg - bidirectional bridge between Git and Mercurial


SYNOPSIS
--------
[verse]
'git clone' hg::<hg repository>


DESCRIPTION
-----------

This tool allows you to transparently clone, fetch and push to and from Mercurial
repositories as if they were Git ones.

To use it you simply need to use the "'hg::'" prefix when specifying a remote URL
(e.g. when cloning).


EXAMPLE
-------
------------
$ git clone hg::http://selenic.com/repo/hello
------------


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 Mercurial named 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:password@bitbucket.org/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].

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]).