1GIT-REMOTE-HG(1)                                              GIT-REMOTE-HG(1)
2
3
4

NAME

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

SYNOPSIS

9       git clone hg::<hg repository>
10

DESCRIPTION

12       This tool allows you to transparently clone, fetch and push to and from
13       Mercurial repositories as if they were Git ones.
14
15       To use it you simply need to use the "hg::" prefix when specifying a
16       remote URL (e.g. when cloning).
17

EXAMPLE

19           $ git clone hg::http://selenic.com/repo/hello
20

CONFIGURATION

22       If you want to see Mercurial revisions as Git commit notes:
23
24           % git config core.notesRef refs/notes/hg
25
26       If you are not interested in Mercurial permanent and global branches
27       (aka. commit labels):
28
29           % git config --global remote-hg.track-branches false
30
31       With this configuration, the branches/foo refs won’t appear.
32
33       If you want the equivalent of hg clone --insecure:
34
35           % git config --global remote-hg.insecure true
36
37       If you want git-remote-hg to be compatible with hg-git, and generate
38       exactly the same commits:
39
40           % git config --global remote-hg.hg-git-compat true
41
42       If you would like (why?) the old behaviour (export capability) where
43       various limitations apply:
44
45           % git config --global remote-hg.capability-push false
46
47       In the new behaviour, performing a git push will make git search for
48       and detect file rename and copy and turn this into Mercurial commit
49       metadata. To tweak how this detection happens, e.g. have it search even
50       more:
51
52           % git config --global remote-hg.fast-export-options '-M -C -C'
53
54       The default otherwise is simply -M -C. See also e.g. git-log(1) manpage
55       for more details on the options used to tweak this.
56
57       As the old refs/hg/... are actually an implementation detail, they are
58       now maintained not so visibly. If that, however, would be preferred:
59
60           % git config --global remote-hg.show-private-refs true
61
62       Use of shared marks files is the default in a new repo, but can also be
63       enabled for an existing repo:
64
65           % git config --global remote-hg.shared-marks true
66
67       Note that one should perform a fetch from each remote to properly
68       complete the conversion to shared marks files.
69
70       Mercurial name(s) (of a branch or bookmark) that are not a valid git
71       refname, can be ignored by configuring a suitable regular expression,
72       e.g. avoiding the invalid ~
73
74           % git config --global remote-hg.ignore-name ~
75

NOTES

77       Remember to run git gc --aggressive after cloning a repository,
78       specially if it’s a big one. Otherwise lots of space will be wasted.
79
80       The oldest version of Mercurial supported is 1.9. For the most part 1.8
81       works, but you might experience some issues.
82
83   Pushing branches
84       To push a Mercurial named branch, you need to use the "branches/"
85       prefix:
86
87           % git checkout branches/next
88           # do stuff
89           % git push origin branches/next
90
91       All the pushed commits will receive the "next" Mercurial named branch.
92
93       Note: Make sure you don’t have remote-hg.track-branches disabled.
94
95   Cloning HTTPS
96       The simplest way is to specify the user and password in the URL:
97
98           git clone hg::https://user:password@bitbucket.org/user/repo
99
100       You can also use the schemes extension:
101
102           [auth]
103           bb.prefix = https://bitbucket.org/user/
104           bb.username = user
105           bb.password = password
106
107       Finally, you can also use the keyring extension.
108

CAVEATS

110       The only major incompatibility is that Git octopus merges (a merge with
111       more than two parents) are not supported.
112
113       Mercurial branches and bookmarks have some limitations of Git branches:
114       you can’t have both dev/feature and dev (as Git uses files and
115       directories to store them).
116
117       Multiple anonymous heads (which are useless anyway) are not supported;
118       you would only see the latest head.
119
120       Closed branches are not supported; they are not shown and you can’t
121       close or reopen. Additionally in certain rare situations a
122       synchronization issue can occur (Bug #65).
123

TECHNICAL DISCUSSION

125       As git-remote-hg is a developer tool after all, it might be interesting
126       to know a bit about what is going on behind the scenes, without
127       necessarily going into all the details.
128
129       So let’s first have a look in the .git/hg directory, which typically
130       contains a subdirectory for each remote Mercurial repo alias, as well
131       as a .hg subdirectory. If the Mercurial repo is a local one, it will
132       (again typically) only contain a marks-git and a marks-hg file. If the
133       repo is a remote one, then the clone contains, well, a local clone of
134       the remote. However, all these clones share storage through the .hg
135       directory mentioned previously (so they do not add up separately).
136       During a fetch/push, the local (proxy) repo is used as an intermediate
137       stage. If you would also prefer such an intermediate stage for local
138       repos, then setting the environment variable GIT_REMOTE_HG_TEST_REMOTE
139       will also use a proxy repo clone for a local repo.
140
141       As for the marks files, marks-git is created and used by
142       git-fast-export and git-fast-import and contains a mapping from mark to
143       commit hash, where a mark is essentially a plain number. marks-hg
144       similarly contains a (JSON) based mapping between such mark and hg
145       revision hash. Together they provide for a (consistent) view of the
146       synchronization state of things.
147
148       When operating with shared-marks files, the marks-git and marks-hg
149       files are shared among all repos. As such, they are then found in the
150       .git/hg directory (rather than a repo subdirectory). As there is really
151       only one hg repository (the shared storage "union bag" in .git/hg/.hg),
152       only 1 set of marks files should track the mapping between commit hash
153       and revision hash. Each individual remote then only adds some metadata
154       (e.g regarding heads).
155
156       Upon a fetch, the helper uses the marks-hg file to decide what is
157       already present and what not. The required parts are then retrieved
158       from Mercurial and turned into a git-fast-import stream as expected by
159       import capability of gitremote-helpers(1).
160
161       Upon a push, the helper has specified the push capability in the new
162       approach, and so git will provide a list of refspecs indicating what
163       should go where. If the refspecs indicates a remote delete, it is
164       performed appropriately the Mercurial way. If it is a regular push,
165       then git-fast-export is invoked (using the existing marks-git) and the
166       stream is processed and turned into Mercurial commits (along with
167       bookmarks, etc). If the refspec specifies a src:dest rename, then the
168       requested remote refname is tracked accordingly. If a dry-run is
169       requested, no remote is touched and no (marks) state of the run is
170       retained.
171
172
173
174                                  07/25/2019                  GIT-REMOTE-HG(1)
Impressum