git-rebase.txt: document behavioral differences between modes
There are a variety of aspects that are common to all rebases regardless of which backend is in use; however, the behavior for these different aspects varies in ways that could surprise users. (In fact, it's not clear -- to me at least -- that these differences were even desirable or intentional.) Document these differences. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>maint
parent
4d34dffbdd
commit
0661e49aeb
|
@ -546,6 +546,38 @@ Other incompatible flag pairs:
|
||||||
* --rebase-merges and --strategy
|
* --rebase-merges and --strategy
|
||||||
* --rebase-merges and --strategy-option
|
* --rebase-merges and --strategy-option
|
||||||
|
|
||||||
|
BEHAVIORAL DIFFERENCES
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
* empty commits:
|
||||||
|
|
||||||
|
am-based rebase will drop any "empty" commits, whether the
|
||||||
|
commit started empty (had no changes relative to its parent to
|
||||||
|
start with) or ended empty (all changes were already applied
|
||||||
|
upstream in other commits).
|
||||||
|
|
||||||
|
merge-based rebase does the same.
|
||||||
|
|
||||||
|
interactive-based rebase will by default drop commits that
|
||||||
|
started empty and halt if it hits a commit that ended up empty.
|
||||||
|
The `--keep-empty` option exists for interactive rebases to allow
|
||||||
|
it to keep commits that started empty.
|
||||||
|
|
||||||
|
* empty commit messages:
|
||||||
|
|
||||||
|
am-based rebase will silently apply commits with empty commit
|
||||||
|
messages.
|
||||||
|
|
||||||
|
merge-based and interactive-based rebases will by default halt
|
||||||
|
on any such commits. The `--allow-empty-message` option exists to
|
||||||
|
allow interactive-based rebases to apply such commits without
|
||||||
|
halting.
|
||||||
|
|
||||||
|
* directory rename detection:
|
||||||
|
|
||||||
|
merge-based and interactive-based rebases work fine with
|
||||||
|
directory rename detection. am-based rebases sometimes do not.
|
||||||
|
|
||||||
include::merge-strategies.txt[]
|
include::merge-strategies.txt[]
|
||||||
|
|
||||||
NOTES
|
NOTES
|
||||||
|
|
|
@ -90,3 +90,26 @@ directory rename detection support in:
|
||||||
simply not implemented. Further, to implement this, directory rename
|
simply not implemented. Further, to implement this, directory rename
|
||||||
detection logic would need to move from merge-recursive to
|
detection logic would need to move from merge-recursive to
|
||||||
diffcore-rename.
|
diffcore-rename.
|
||||||
|
|
||||||
|
* am
|
||||||
|
|
||||||
|
git-am tries to avoid a full three way merge, instead calling
|
||||||
|
git-apply. That prevents us from detecting renames at all, which may
|
||||||
|
defeat the directory rename detection. There is a fallback, though; if
|
||||||
|
the initial git-apply fails and the user has specified the -3 option,
|
||||||
|
git-am will fall back to a three way merge. However, git-am lacks the
|
||||||
|
necessary information to do a "real" three way merge. Instead, it has
|
||||||
|
to use build_fake_ancestor() to get a merge base that is missing files
|
||||||
|
whose rename may have been important to detect for directory rename
|
||||||
|
detection to function.
|
||||||
|
|
||||||
|
* rebase
|
||||||
|
|
||||||
|
Since am-based rebases work by first generating a bunch of patches
|
||||||
|
(which no longer record what the original commits were and thus don't
|
||||||
|
have the necessary info from which we can find a real merge-base), and
|
||||||
|
then calling git-am, this implies that am-based rebases will not always
|
||||||
|
successfully detect directory renames either (see the 'am' section
|
||||||
|
above). merged-based rebases (rebase -m) and cherry-pick-based rebases
|
||||||
|
(rebase -i) are not affected by this shortcoming, and fully support
|
||||||
|
directory rename detection.
|
||||||
|
|
Loading…
Reference in New Issue