From: Elijah Newren <newren@gmail.com>
To: git@vger.kernel.org
Cc: gitster@pobox.com, phillip.wood@dunelm.org.uk,
johannes.schindelin@gmx.de, sunshine@sunshineco.com,
Elijah Newren <newren@gmail.com>
Subject: [PATCH v3 5/7] git-rebase.txt: document behavioral inconsistencies between modes
Date: Thu, 21 Jun 2018 08:00:21 -0700 [thread overview]
Message-ID: <20180621150023.23533-6-newren@gmail.com> (raw)
In-Reply-To: <20180621150023.23533-1-newren@gmail.com>
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>
---
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
next prev parent reply other threads:[~2018-06-21 15:00 UTC|newest]
Thread overview: 130+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-06-07 4:58 RFC: rebase inconsistency in 2.18 -- course of action? Elijah Newren
2018-06-07 5:04 ` [PATCH] t3401: add directory rename testcases for rebase and am Elijah Newren
2018-06-25 16:17 ` Elijah Newren
2018-06-07 5:05 ` [PATCH] apply: fix grammar error in comment Elijah Newren
2018-06-07 5:05 ` [PATCH] t5407: fix test to cover intended arguments Elijah Newren
2018-06-07 5:06 ` [PATCH] git-rebase--merge: modernize "git-$cmd" to "git $cmd" Elijah Newren
2018-06-07 5:24 ` Elijah Newren
2018-06-27 7:46 ` [PATCH v2] " Elijah Newren
2018-07-12 15:49 ` Johannes Schindelin
2018-07-13 16:13 ` Elijah Newren
2018-07-14 22:20 ` Johannes Schindelin
2018-06-07 5:06 ` [PATCH 1/2] t3422: new testcases for checking when incompatible options passed Elijah Newren
2018-06-07 5:06 ` [PATCH 2/2] git-rebase: error out " Elijah Newren
2018-06-10 19:40 ` Phillip Wood
2018-06-11 15:19 ` Elijah Newren
2018-06-11 15:59 ` Phillip Wood
2018-06-11 15:49 ` Elijah Newren
2018-06-12 9:45 ` Phillip Wood
2018-06-17 5:58 ` [RFC PATCH v2 0/7] Document/fix/warn about rebase incompatibilities and inconsistences Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 1/7] git-rebase.txt: document incompatible options Elijah Newren
2018-06-17 15:38 ` Phillip Wood
2018-06-20 17:09 ` Elijah Newren
2018-06-17 17:15 ` Eric Sunshine
2018-06-20 17:10 ` Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 2/7] git-rebase.sh: update help messages a bit Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 3/7] t3422: new testcases for checking when incompatible options passed Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 4/7] git-rebase: error out " Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 5/7] git-rebase.txt: document behavioral inconsistencies between modes Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 6/7] git-rebase.txt: address confusion between --no-ff vs --force-rebase Elijah Newren
2018-06-17 5:58 ` [RFC PATCH v2 7/7] git-rebase: make --allow-empty-message the default Elijah Newren
2018-06-17 15:30 ` Phillip Wood
2018-06-20 16:47 ` Elijah Newren
2018-06-17 15:41 ` [RFC PATCH v2 0/7] Document/fix/warn about rebase incompatibilities and inconsistences Phillip Wood
2018-06-21 15:00 ` [PATCH v3 0/7] Document/fix/warn about rebase incompatibilities and inconsistencies Elijah Newren
2018-06-21 15:00 ` [PATCH v3 1/7] git-rebase.txt: document incompatible options Elijah Newren
2018-06-21 19:47 ` Junio C Hamano
2018-06-21 20:33 ` Elijah Newren
2018-06-22 8:32 ` SZEDER Gábor
2018-06-21 15:00 ` [PATCH v3 2/7] git-rebase.sh: update help messages a bit Elijah Newren
2018-06-21 19:58 ` Junio C Hamano
2018-06-21 20:34 ` Elijah Newren
2018-06-21 15:00 ` [PATCH v3 3/7] t3422: new testcases for checking when incompatible options passed Elijah Newren
2018-06-21 20:04 ` Junio C Hamano
2018-06-21 20:37 ` Elijah Newren
2018-06-21 21:18 ` Eric Sunshine
2018-06-21 15:00 ` [PATCH v3 4/7] git-rebase: error out " Elijah Newren
2018-06-21 20:29 ` Junio C Hamano
2018-06-21 20:41 ` Elijah Newren
2018-06-21 15:00 ` Elijah Newren [this message]
2018-06-21 20:44 ` [PATCH v3 5/7] git-rebase.txt: document behavioral inconsistencies between modes Junio C Hamano
2018-06-21 21:25 ` Elijah Newren
2018-06-21 15:00 ` [PATCH v3 6/7] git-rebase.txt: address confusion between --no-ff vs --force-rebase Elijah Newren
2018-06-21 20:46 ` Junio C Hamano
2018-06-21 21:22 ` Elijah Newren
2018-06-21 15:00 ` [RFC PATCH v3 7/7] git-rebase: make --allow-empty-message the default Elijah Newren
2018-06-25 16:12 ` [PATCH v4 0/9] Document/fix/warn about rebase incompatibilities and inconsistencies Elijah Newren
2018-06-25 16:12 ` [PATCH v4 1/9] git-rebase.txt: document incompatible options Elijah Newren
2018-06-25 16:12 ` [PATCH v4 2/9] git-rebase.sh: update help messages a bit Elijah Newren
2018-06-25 16:12 ` [PATCH v4 3/9] t3422: new testcases for checking when incompatible options passed Elijah Newren
2018-06-26 18:17 ` Junio C Hamano
2018-06-27 6:50 ` Elijah Newren
2018-06-25 16:12 ` [PATCH v4 4/9] git-rebase: error out " Elijah Newren
2018-06-25 16:12 ` [PATCH v4 5/9] git-rebase.txt: address confusion between --no-ff vs --force-rebase Elijah Newren
2018-06-25 16:12 ` [PATCH v4 6/9] directory-rename-detection.txt: technical docs on abilities and limitations Elijah Newren
2018-06-25 16:12 ` [PATCH v4 7/9] git-rebase.txt: document behavioral differences between modes Elijah Newren
2018-06-25 16:12 ` [PATCH v4 8/9] t3401: add directory rename testcases for rebase and am Elijah Newren
2018-06-25 16:13 ` [RFC PATCH v4 9/9] git-rebase: make --allow-empty-message the default Elijah Newren
2018-06-27 7:23 ` [PATCH v5 0/9] Document/fix/warn about rebase incompatibilities and inconsistencies Elijah Newren
2018-06-27 7:23 ` [PATCH v5 1/9] git-rebase.txt: document incompatible options Elijah Newren
2018-06-27 7:23 ` [PATCH v5 2/9] git-rebase.sh: update help messages a bit Elijah Newren
2018-06-27 7:23 ` [PATCH v5 3/9] t3422: new testcases for checking when incompatible options passed Elijah Newren
2018-06-27 7:23 ` [PATCH v5 4/9] git-rebase: error out " Elijah Newren
2018-06-27 7:23 ` [PATCH v5 5/9] git-rebase.txt: address confusion between --no-ff vs --force-rebase Elijah Newren
2018-06-27 7:23 ` [PATCH v5 6/9] directory-rename-detection.txt: technical docs on abilities and limitations Elijah Newren
2018-06-27 7:23 ` [PATCH v5 7/9] git-rebase.txt: document behavioral differences between modes Elijah Newren
2018-06-27 7:23 ` [PATCH v5 8/9] t3401: add directory rename testcases for rebase and am Elijah Newren
2018-06-27 7:23 ` [RFC PATCH v5 9/9] git-rebase: make --allow-empty-message the default Elijah Newren
2018-09-12 2:42 ` 2.19.0 regression: leaving editor with empty commit message doesn't stop rebase [was: Re: [RFC PATCH v5 9/9] git-rebase: make --allow-empty-message the default] SZEDER Gábor
2018-09-12 6:21 ` Elijah Newren
2018-09-12 21:18 ` [PATCH] sequencer: fix --allow-empty-message behavior, make it smarter Elijah Newren
2018-09-13 20:24 ` Junio C Hamano
2018-06-29 13:20 ` [PATCH v5 0/9] Document/fix/warn about rebase incompatibilities and inconsistencies Phillip Wood
2018-06-07 5:07 ` [PATCH] git-rebase.sh: handle keep-empty like all other options Elijah Newren
2018-06-10 19:26 ` Phillip Wood
2018-06-11 14:42 ` Elijah Newren
2018-06-11 15:16 ` Phillip Wood
2018-06-11 16:08 ` Elijah Newren
2018-06-12 9:53 ` Phillip Wood
2018-06-07 5:08 ` [PATCH 1/2] t3418: add testcase showing problems with rebase -i and strategy options Elijah Newren
2018-06-07 5:08 ` [PATCH 2/2] Fix use of strategy options with interactive rebases Elijah Newren
2018-06-27 7:36 ` [PATCH v2 0/2] " Elijah Newren
2018-06-27 7:36 ` [PATCH v2 1/2] t3418: add testcase showing problems with rebase -i and strategy options Elijah Newren
2018-06-27 7:45 ` Eric Sunshine
2018-06-27 7:49 ` Elijah Newren
2018-06-27 16:54 ` Junio C Hamano
2018-06-27 17:27 ` Elijah Newren
2018-06-27 18:17 ` Johannes Sixt
2018-06-27 18:24 ` Eric Sunshine
2018-06-27 18:34 ` [PATCH v2 1/2] t3418: add testcase showing problems with rebase SZEDER Gábor
2018-06-27 19:20 ` [PATCH v2 1/2] t3418: add testcase showing problems with rebase -i and strategy options Junio C Hamano
2018-06-27 19:23 ` Junio C Hamano
2018-06-27 7:36 ` [PATCH v2 2/2] Fix use of strategy options with interactive rebases Elijah Newren
2018-06-27 15:48 ` [PATCH v3 0/2] " Elijah Newren
2018-06-27 15:48 ` [PATCH v3 1/2] t3418: add testcase showing problems with rebase -i and strategy options Elijah Newren
2018-06-27 18:28 ` SZEDER Gábor
2018-07-11 10:56 ` SZEDER Gábor
2018-07-11 19:12 ` Elijah Newren
2018-06-27 15:48 ` [PATCH v3 2/2] Fix use of strategy options with interactive rebases Elijah Newren
2018-07-12 15:41 ` Johannes Schindelin
2018-07-13 15:51 ` Elijah Newren
2018-06-07 17:13 ` [RFC PATCH 0/3] Send more rebases through interactive machinery Elijah Newren
2018-06-07 17:13 ` [RFC PATCH 1/3] git-rebase, sequencer: add a --quiet option for the " Elijah Newren
2018-06-09 21:45 ` Johannes Schindelin
2018-06-09 23:05 ` Elijah Newren
2018-06-07 17:13 ` [RFC PATCH 2/3] rebase: Implement --merge via git-rebase--interactive Elijah Newren
2018-06-09 22:04 ` Johannes Schindelin
2018-06-10 1:14 ` Elijah Newren
2018-06-11 9:54 ` Phillip Wood
2018-06-07 17:13 ` [RFC PATCH 3/3] git-rebase.sh: make git-rebase--interactive the default Elijah Newren
2018-06-09 22:11 ` Johannes Schindelin
2018-06-10 1:31 ` Elijah Newren
2018-06-17 21:44 ` Johannes Schindelin
2018-06-20 16:27 ` Elijah Newren
2018-06-21 10:57 ` Johannes Schindelin
2018-06-21 15:36 ` Elijah Newren
2019-01-21 15:55 ` Johannes Schindelin
2019-01-21 19:02 ` Elijah Newren
2019-01-22 15:37 ` Johannes Schindelin
2018-06-11 17:44 ` RFC: rebase inconsistency in 2.18 -- course of action? Junio C Hamano
2018-06-11 20:17 ` Elijah Newren
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180621150023.23533-6-newren@gmail.com \
--to=newren@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=johannes.schindelin@gmx.de \
--cc=phillip.wood@dunelm.org.uk \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).