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@xxxxxxxxx> --- Documentation/git-rebase.txt | 57 ++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 7de6523931..340137e2cf 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -556,6 +556,63 @@ Other incompatible flag pairs: * --rebase-merges and --strategy * --rebase-merges and --strategy-option +BEHAVIORAL INCONSISTENCIES +-------------------------- + + * --no-ff vs. --force-rebase + + These options are actually identical, though their description + leads people to believe they might not be. + + * 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. + + 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. + + 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. merged-based rebases (rebase -m) and + cherry-pick-based rebases (rebase -i) are not affected by this + shortcoming. + include::merge-strategies.txt[] NOTES -- 2.18.0.rc2.92.g133ed01dde
