path: root/Documentation/technical
diff options
authorElijah Newren <>2018-06-27 07:23:17 (GMT)
committerJunio C Hamano <>2018-06-27 18:23:22 (GMT)
commit0661e49aeb842a29f2ebbd7b005ec5824c2b87e1 (patch)
tree2eefeb88be6af711961ec0112434794b9be229c8 /Documentation/technical
parent4d34dffbdd2226034df9d7612f1e221b7143fc6a (diff)
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 <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical')
1 files changed, 23 insertions, 0 deletions
diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt
index 6e22920..1c0086e 100644
--- a/Documentation/technical/directory-rename-detection.txt
+++ b/Documentation/technical/directory-rename-detection.txt
@@ -90,3 +90,26 @@ directory rename detection support in:
simply not implemented. Further, to implement this, directory rename
detection logic would need to move from merge-recursive to
+ * 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.