diff --git a/README.asciidoc b/README.asciidoc index e53aaba..6378c38 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -17,6 +17,17 @@ 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 <> as mentioned below +* properly annotates copy/rename when pushing new commits to Mercurial + +See sections below or sidemarked notes for more details. +**** + == Configuration == If you want to see Mercurial revisions as Git commit notes: @@ -107,6 +118,7 @@ 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: @@ -114,10 +126,25 @@ commands don't work: * `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 <> +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: +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] @@ -125,6 +152,38 @@ this is the one distributed officially by the Git project: 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 <> 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 ` 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.