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>
Elijah Newren committed
Jun 27, 2018 at 00:23 UTC
0661e49aeb842a29f2ebbd7b005ec5824c2b87e1
2 files changed
+55
Documentation/git-rebase.txt
+32
@@ -546,6 +546,38 @@ Other incompatible flag pairs:
546
* --rebase-merges and --strategy
547
* --rebase-merges and --strategy-option
548
549
+BEHAVIORAL DIFFERENCES
550
+-----------------------
551
+
552
+ * empty commits:
553
+
554
+ am-based rebase will drop any "empty" commits, whether the
555
+ commit started empty (had no changes relative to its parent to
556
+ start with) or ended empty (all changes were already applied
557
+ upstream in other commits).
558
+
559
+ merge-based rebase does the same.
560
+
561
+ interactive-based rebase will by default drop commits that
562
+ started empty and halt if it hits a commit that ended up empty.
563
+ The `--keep-empty` option exists for interactive rebases to allow
564
+ it to keep commits that started empty.
565
+
566
+ * empty commit messages:
567
+
568
+ am-based rebase will silently apply commits with empty commit
569
+ messages.
570
+
571
+ merge-based and interactive-based rebases will by default halt
572
+ on any such commits. The `--allow-empty-message` option exists to
573
+ allow interactive-based rebases to apply such commits without
574
+ halting.
575
+
576
+ * directory rename detection:
577
+
578
+ merge-based and interactive-based rebases work fine with
579
+ directory rename detection. am-based rebases sometimes do not.
580
+
581
include::merge-strategies.txt[]
582
583
NOTES
Documentation/technical/directory-rename-detection.txt
+23
@@ -90,3 +90,26 @@ directory rename detection support in:
90
simply not implemented. Further, to implement this, directory rename
91
detection logic would need to move from merge-recursive to
92
diffcore-rename.
93
+
94
+ * am
95
+
96
+ git-am tries to avoid a full three way merge, instead calling
97
+ git-apply. That prevents us from detecting renames at all, which may
98
+ defeat the directory rename detection. There is a fallback, though; if
99
+ the initial git-apply fails and the user has specified the -3 option,
100
+ git-am will fall back to a three way merge. However, git-am lacks the
101
+ necessary information to do a "real" three way merge. Instead, it has
102
+ to use build_fake_ancestor() to get a merge base that is missing files
103
+ whose rename may have been important to detect for directory rename
104
+ detection to function.
105
+
106
+ * rebase
107
+
108
+ Since am-based rebases work by first generating a bunch of patches
109
+ (which no longer record what the original commits were and thus don't
110
+ have the necessary info from which we can find a real merge-base), and
111
+ then calling git-am, this implies that am-based rebases will not always
112
+ successfully detect directory renames either (see the 'am' section
113
+ above). merged-based rebases (rebase -m) and cherry-pick-based rebases
114
+ (rebase -i) are not affected by this shortcoming, and fully support
115
+ directory rename detection.