1GIT-REMOTE-HG(1) GIT-REMOTE-HG(1)
2
6 git-remote-hg - bidirectional bridge between Git and Mercurial
7
9 git clone hg::<hg repository>
10
12 This tool allows you to transparently clone, fetch and push to and from
13 Mercurial repositories as if they were Git ones.
14 To use it you simply need to use the "hg::" prefix when specifying a
16 remote URL (e.g. when cloning).
17
19 $ git clone hg::http://selenic.com/repo/hello
20
22 If you want to see Mercurial revisions as Git commit notes:
23 % git config core.notesRef refs/notes/hg
25 If you are not interested in Mercurial permanent and global branches
27 (aka. commit labels):
28 % git config --global remote-hg.track-branches false
30 With this configuration, the branches/foo refs won’t appear.
32 If you want the equivalent of hg clone --insecure:
34 % git config --global remote-hg.insecure true
36 If you want git-remote-hg to be compatible with hg-git, and generate
38 exactly the same commits:
39 % git config --global remote-hg.hg-git-compat true
41 If you would like (why?) the old behaviour (export capability) where
43 various limitations apply:
44 % git config --global remote-hg.capability-push false
46 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 % git config --global remote-hg.fast-export-options '-M -C -C'
53 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 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 % git config --global remote-hg.show-private-refs true
61 Use of shared marks files is the default in a new repo, but can also be
63 enabled for an existing repo:
64 % git config --global remote-hg.shared-marks true
66 Note that one should perform a fetch from each remote to properly
68 complete the conversion to shared marks files.
69 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 % git config --global remote-hg.ignore-name ~
75
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 The oldest version of Mercurial supported is 1.9. For the most part 1.8
81 works, but you might experience some issues.
82 Pushing branches
84 To push a Mercurial named branch, you need to use the "branches/"
85 prefix:
86 % git checkout branches/next
88 # do stuff
89 % git push origin branches/next
90 All the pushed commits will receive the "next" Mercurial named branch.
92 Note: Make sure you don’t have remote-hg.track-branches disabled.
94 Cloning HTTPS
96 The simplest way is to specify the user and password in the URL:
97 git clone hg::https://user:password@bitbucket.org/user/repo
99 You can also use the schemes extension:
101 [auth]
103 bb.prefix = https://bitbucket.org/user/
104 bb.username = user
105 bb.password = password
106 Finally, you can also use the keyring extension.
108
110 The only major incompatibility is that Git octopus merges (a merge with
111 more than two parents) are not supported.
112 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 Multiple anonymous heads (which are useless anyway) are not supported;
118 you would only see the latest head.
119 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
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 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 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 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 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 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 07/22/2021 GIT-REMOTE-HG(1)