NAME

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

SYNOPSIS

       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

       If you would like (why?) the old behaviour (export capability) where various limitations
       apply:

           % git config --global remote-hg.capability-push false

       In the new behaviour, performing a git push will make git search for and detect file
       rename and copy and turn this into Mercurial commit metadata. To tweak how this detection
       happens, e.g. have it search even more:

           % git config --global remote-hg.fast-export-options '-M -C -C'

       The default otherwise is simply -M -C. See also e.g. git-log(1) manpage for more details
       on the options used to tweak this.

       As the old refs/hg/... are actually an implementation detail, they are now maintained not
       so visibly. If that, however, would be preferred:

           % git config --global remote-hg.show-private-refs true

       Use of shared marks files is the default in a new repo, but can also be enabled for an
       existing repo:

           % git config --global remote-hg.shared-marks true

       Note that one should perform a fetch from each remote to properly complete the conversion
       to shared marks files.

       Mercurial name(s) (of a branch or bookmark) that are not a valid git refname, can be
       ignored by configuring a suitable regular expression, e.g. avoiding the invalid ~

           % git config --global remote-hg.ignore-name ~

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 schemes extension:

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

       Finally, you can also use the 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 (Bug #65).

TECHNICAL DISCUSSION

       As git-remote-hg is a developer tool after all, it might be interesting to know a bit
       about what is going on behind the scenes, without necessarily going into all the details.

       So let’s first have a look in the .git/hg directory, which typically contains a
       subdirectory for each remote Mercurial repo alias, as well as a .hg subdirectory. If the
       Mercurial repo is a local one, it will (again typically) only contain a marks-git and a
       marks-hg file. If the repo is a remote one, then the clone contains, well, a local clone
       of the remote. However, all these clones share storage through the .hg directory mentioned
       previously (so they do not add up separately). During a fetch/push, the local (proxy) repo
       is used as an intermediate stage. If you would also prefer such an intermediate stage for
       local repos, then setting the environment variable GIT_REMOTE_HG_TEST_REMOTE will also use
       a proxy repo clone for a local repo.

       As for the marks files, marks-git is created and used by git-fast-export and
       git-fast-import and contains a mapping from mark to commit hash, where a mark is
       essentially a plain number. marks-hg similarly contains a (JSON) based mapping between
       such mark and hg revision hash. Together they provide for a (consistent) view of the
       synchronization state of things.

       When operating with shared-marks files, the marks-git and marks-hg files are shared among
       all repos. As such, they are then found in the .git/hg directory (rather than a repo
       subdirectory). As there is really only one hg repository (the shared storage "union bag"
       in .git/hg/.hg), only 1 set of marks files should track the mapping between commit hash
       and revision hash. Each individual remote then only adds some metadata (e.g regarding
       heads).

       Upon a fetch, the helper uses the marks-hg file to decide what is already present and what
       not. The required parts are then retrieved from Mercurial and turned into a
       git-fast-import stream as expected by import capability of gitremote-helpers(1).

       Upon a push, the helper has specified the push capability in the new approach, and so git
       will provide a list of refspecs indicating what should go where. If the refspecs indicates
       a remote delete, it is performed appropriately the Mercurial way. If it is a regular push,
       then git-fast-export is invoked (using the existing marks-git) and the stream is processed
       and turned into Mercurial commits (along with bookmarks, etc). If the refspec specifies a
       src:dest rename, then the requested remote refname is tracked accordingly. If a dry-run is
       requested, no remote is touched and no (marks) state of the run is retained.

                                            03/26/2022                           GIT-REMOTE-HG(1)