mirror of
https://github.com/mnauw/git-remote-hg.git
synced 2025-10-26 06:06:06 +01:00
191 lines
7.1 KiB
Plaintext
191 lines
7.1 KiB
Plaintext
'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"
|
|
--------------------------------------
|
|
|
|
To enable this, simply add the 'git-remote-hg' script anywhere in your `$PATH`:
|
|
|
|
--------------------------------------
|
|
wget https://raw.github.com/mnauw/git-remote-hg/master/git-remote-hg -O ~/bin/git-remote-hg
|
|
chmod +x ~/bin/git-remote-hg
|
|
--------------------------------------
|
|
|
|
That's it :)
|
|
|
|
Obviously you will need Mercurial installed.
|
|
|
|
****
|
|
At present, this "working copy"/fork adds the following features
|
|
(and I would prefer it is indeed rather a "working copy"
|
|
to be appropriately merged upstream):
|
|
|
|
* eliminates a number of <<limitations, limitations>> as mentioned below
|
|
* properly annotates copy/rename when pushing new commits to Mercurial
|
|
* avoids clutter of `refs/hg/...` by keeping these implementation details really private
|
|
|
|
See sections below or sidemarked notes for more details.
|
|
****
|
|
|
|
== 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: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].
|
|
|
|
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]]
|
|
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)
|
|
|
|
****
|
|
Another limitation is that if `git log` reports a rename, this will not survive
|
|
the push and Mercurial will not be aware of a rename (and similarly so for copy).
|
|
Though Mercurial would know about it if you *manually* ran `git-format-patch`
|
|
followed by a `hg apply -s`, which is not the nice way to go obviously.
|
|
|
|
Actually, scratch the limitations above ascribed to the remote-helpers framework.
|
|
They are not limitations of the framework, but are due to how the original
|
|
implementation of 'git-remote-hg' interacts with it.
|
|
Using the remote-helpers framework in only a slightly different way has none
|
|
of the above limitations. See the <<no-limitations, relevant section>>
|
|
below for more details.
|
|
****
|
|
|
|
== 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
|
|
(_though actually no longer so nowadays_):
|
|
|
|
* 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].
|
|
|
|
[[no-limitations]]
|
|
== Limitations (or not) ==
|
|
|
|
If interested in some of technical details behind this explanation, then also
|
|
see the relevant section in 'git-remote-hg' manpage. Otherwise, the general
|
|
idea is presented here.
|
|
|
|
More precisely and simply, the <<limitations, mentioned limitations>> are indeed
|
|
limitations of the `export` capability of
|
|
https://www.kernel.org/pub/software/scm/git/docs/gitremote-helpers.html[gitremote-helpers(1)]
|
|
framework. However, the framework also supports a `push` capability and when this
|
|
is used appropriately in the remote helper the aforementioned limitations do not apply.
|
|
In the case of `export` capability, git-core will internally invoke `git-fast-export`
|
|
and the helper will process this data and hand over generated changesets to Mercurial.
|
|
In the case of `push` capability, git informs the helper what (refs) should go where,
|
|
and the helper is free to ponder about this and take the required action, such as
|
|
to invoke `git-fast-export` itself (with suitable options) and process its output
|
|
the same way as before (and over to Mercurial).
|
|
|
|
And so;
|
|
|
|
* `git push origin :branch-to-delete` will delete the bookmark `branch-to-delete` on remote
|
|
* `git push --dry-run origin branch` will not touch the remote
|
|
(or any local state, except for local helper proxy repo)
|
|
* `git push origin old:new` will push `old` onto `new` in the remote
|
|
* `git push origin <history-with-copy/rename>` will push copy/rename aware Mercurial revisions
|
|
|
|
To tweak how 'git-remote-hg' decides on a copy/rename, use e.g:
|
|
--------------------------------------
|
|
% git config --global remote-hg.fast-export-options '-M -C -C'
|
|
--------------------------------------
|
|
|
|
== Contributing ==
|
|
|
|
Please file an issue with some patches or a pull-request.
|