diff options
author | Elijah Newren <newren@gmail.com> | 2018-06-27 07:23:17 (GMT) |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2018-06-27 18:23:22 (GMT) |
commit | 0661e49aeb842a29f2ebbd7b005ec5824c2b87e1 (patch) | |
tree | 2eefeb88be6af711961ec0112434794b9be229c8 /Documentation | |
parent | 4d34dffbdd2226034df9d7612f1e221b7143fc6a (diff) | |
download | git-0661e49aeb842a29f2ebbd7b005ec5824c2b87e1.zip git-0661e49aeb842a29f2ebbd7b005ec5824c2b87e1.tar.gz git-0661e49aeb842a29f2ebbd7b005ec5824c2b87e1.tar.bz2 |
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>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/git-rebase.txt | 32 | ||||
-rw-r--r-- | Documentation/technical/directory-rename-detection.txt | 23 |
2 files changed, 55 insertions, 0 deletions
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 2f47495..a67df4c 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -546,6 +546,38 @@ Other incompatible flag pairs: * --rebase-merges and --strategy * --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[] NOTES 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 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. |