From: "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> To: git@vger.kernel.org Cc: Johannes.Schindelin@gmx.de, phillip.wood@dunelm.org.uk, liu.denton@gmail.com, gitster@pobox.com, plroskin@gmail.com, alban.gruin@gmail.com, szeder.dev@gmail.com, Junio C Hamano <gitster@pobox.com>, Elijah Newren <newren@gmail.com> Subject: [PATCH v2 08/15] git-rebase.txt: add more details about behavioral differences of backends Date: Mon, 23 Dec 2019 18:49:52 +0000 Message-ID: <b307340f7c79c87b2b5a5a2a25d98ef68be4ba4f.1577127000.git.gitgitgadget@gmail.com> (raw) In-Reply-To: <pull.679.v2.git.git.1577126999.gitgitgadget@gmail.com> From: Elijah Newren <newren@gmail.com> Signed-off-by: Elijah Newren <newren@gmail.com> --- Documentation/git-rebase.txt | 102 +++++++++++++++++++++--- t/t3433-rebase-options-compatibility.sh | 5 +- 2 files changed, 94 insertions(+), 13 deletions(-) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index ff32ca1080..f1ace07c38 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -409,13 +409,10 @@ your branch contains commits which were dropped, this option can be used with `--keep-base` in order to drop those commits from your branch. --ignore-whitespace:: - Behaves differently depending on which backend is selected. -+ -'am' backend: When applying a patch, ignore changes in whitespace in -context lines if necessary. -+ -'interactive' backend: Treat lines with only whitespace changes as -unchanged for the sake of a three-way merge. + Ignore whitespace-only changes in the commits being rebased, + which may avoid "unnecessary" conflicts. (Both backends + currently have differing edgecase bugs with this option; see + BEHAVIORAL DIFFERENCES.) --whitespace=<option>:: This flag is passed to the 'git apply' program @@ -609,9 +606,94 @@ There are some subtle differences how the backends behave. Directory rename detection ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Directory rename heuristics are enabled in the merge and interactive -backends. Due to the lack of accurate tree information, directory -rename detection is disabled in the am backend. +Due to the lack of accurate tree information (arising from +constructing fake ancestors with the limited information available in +patches), directory rename detection is disabled in the am backend. +Disabled directory rename detection means that if one side of history +renames a directory and the other adds new files to the old directory, +then the new files will be left behind in the old directory without +any warning at the time of rebasing that you may want to move these +files into the new directory. + +Directory rename detection works with the merge and interactive +backends to provide you warnings in such cases. + +Context +~~~~~~~ + +The am backend works by creating a sequence of patches (by calling +`format-patch` internally), and then applying the patches in sequence +(calling `am` internally). Patches are composed of multiple hunks, +each with line numbers, a context region, and the actual changes. The +line numbers have to be taken with some fuzz, since the other side +will likely have inserted or deleted lines earlier in the file. The +context region is meant to help find how to adjust the line numbers in +order to apply the changes to the right lines. However, if multiple +areas of the code have the same surrounding lines of context, the +wrong one can be picked. There are real-world cases where this has +caused commits to be reapplied incorrectly with no conflicts reported. +Setting diff.context to a larger value may prevent such types of +problems, but increases the chance of spurious conflicts (since it +will require more lines of matching context to apply). + +The interactive backend works with a full copy of each relevant file, +insulating it from these types of problems. + +Labelling of conflicts markers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When there are content conflicts, the merge machinery tries to +annotate each side's conflict markers with the commits where the +content came from. Since the am backend drops the original +information about the rebased commits and their parents (and instead +generates new fake commits based off limited information in the +generated patches), those commits cannot be identified; instead it has +to fall back to a commit summary. Also, when merge.conflictStyle is +set to diff3, the am backend will use "constructed merge base" to +label the content from the merge base, and thus provide no information +about the merge base commit whatsoever. + +The interactive backend works with the full commits on both sides of +history and thus has no such limitations. + +--ignore-whitespace +~~~~~~~~~~~~~~~~~~~ + +The --ignore-whitespace option is supposed to ignore whitespace-only +changes if it allows the code to merge cleanly. Unfortunately, the +different backends implement this differently, and both have different +edge case bugs. ++ +'am' backend: When applying a patch, ignore changes in whitespace in +context lines if necessary. (Which implies that if the whitespace +change was not in the context lines but on a line with a real change, +then the rebase will still fail with "unnecessary" content conflicts.) ++ +'interactive' backend: Treat lines with only whitespace changes as +unchanged for the sake of a three-way merge. This means that if one +side made no changes and the commits being rebased had whitespace-only +changes, those whitespaces fixups will be discarded despite the fact +that they present no content conflict. + +Miscellaneous differences +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few more behavioral differences that most folks would +probably consider inconsequential but which are mentioned for +completeness: + +* Reflog: The two backends will use different wording when describing + the changes made in the reflog, though both will make use of the + word "rebase". + +* Progress, informational, and error messages: The two backends + provide slightly different progress and informational messages. + Also, the am backend writes error messages (such as "Your files + would be overwritten...") to stdout, while the interactive backend + writes them to stderr. + +* State directories: The two backends keep their state in different + directories under .git/ include::merge-strategies.txt[] diff --git a/t/t3433-rebase-options-compatibility.sh b/t/t3433-rebase-options-compatibility.sh index 5166f158dd..bd4d2d2f63 100755 --- a/t/t3433-rebase-options-compatibility.sh +++ b/t/t3433-rebase-options-compatibility.sh @@ -10,9 +10,8 @@ test_description='tests to ensure compatibility between am and interactive backe GIT_AUTHOR_DATE="1999-04-02T08:03:20+05:30" export GIT_AUTHOR_DATE -# This is a special case in which both am and interactive backends -# provide the same output. It was done intentionally because -# both the backends fall short of optimal behaviour. +# This is a common case in which both am and interactive backends +# provide the same output with --ignore-whitespace. test_expect_success 'setup' ' git checkout -b topic && q_to_tab >file <<-\EOF && -- gitgitgadget
next prev parent reply index Thread overview: 161+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-12-20 17:09 [PATCH 00/15] rebase: make the default backend configurable Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 01/15] rebase: extend the options for handling of empty commits Elijah Newren via GitGitGadget 2019-12-20 21:29 ` Junio C Hamano 2019-12-21 0:32 ` Elijah Newren 2019-12-21 18:52 ` Elijah Newren 2019-12-21 23:49 ` Junio C Hamano 2019-12-20 17:09 ` [PATCH 02/15] t3406: simplify an already simple test Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 03/15] rebase, sequencer: remove the broken GIT_QUIET handling Elijah Newren via GitGitGadget 2019-12-20 21:34 ` Junio C Hamano 2019-12-20 17:09 ` [PATCH 04/15] rebase: make sure to pass along the quiet flag to the sequencer Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 05/15] rebase: fix handling of restrict_revision Elijah Newren via GitGitGadget 2019-12-20 21:37 ` Junio C Hamano 2019-12-20 17:09 ` [PATCH 06/15] t3432: make these tests work with either am or merge backends Elijah Newren via GitGitGadget 2019-12-22 5:11 ` Denton Liu 2019-12-23 17:17 ` Elijah Newren 2019-12-20 17:09 ` [PATCH 07/15] rebase: allow more types of rebases to fast-forward Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 08/15] git-rebase.txt: add more details about behavioral differences of backends Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 09/15] rebase: move incompatibility checks between backend options a bit earlier Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 10/15] rebase: add an --am option Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 11/15] contrib: change the prompt for am-based rebases Elijah Newren via GitGitGadget 2019-12-20 23:07 ` SZEDER Gábor 2019-12-21 0:17 ` Elijah Newren 2019-12-20 17:09 ` [PATCH 12/15] rebase tests: mark tests specific to the am-backend with --am Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 13/15] rebase tests: repeat some tests using the merge backend instead of am Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 14/15] rebase: make the backend configurable via config setting Elijah Newren via GitGitGadget 2019-12-20 17:09 ` [PATCH 15/15] rebase: change the default backend from "am" to "merge" Elijah Newren via GitGitGadget 2019-12-20 18:51 ` [PATCH 00/15] rebase: make the default backend configurable Alban Gruin 2019-12-20 18:55 ` Elijah Newren 2019-12-23 18:49 ` [PATCH v2 " Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 01/15] rebase: extend the options for handling of empty commits Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 02/15] t3406: simplify an already simple test Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 03/15] rebase, sequencer: remove the broken GIT_QUIET handling Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 04/15] rebase: make sure to pass along the quiet flag to the sequencer Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 05/15] rebase: fix handling of restrict_revision Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 06/15] t3432: make these tests work with either am or merge backends Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 07/15] rebase: allow more types of rebases to fast-forward Elijah Newren via GitGitGadget 2019-12-23 18:49 ` Elijah Newren via GitGitGadget [this message] 2019-12-23 18:49 ` [PATCH v2 09/15] rebase: move incompatibility checks between backend options a bit earlier Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 10/15] rebase: add an --am option Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 11/15] contrib: change the prompt for interactive-based rebases Elijah Newren via GitGitGadget 2019-12-23 22:00 ` Denton Liu 2019-12-23 18:49 ` [PATCH v2 12/15] rebase tests: mark tests specific to the am-backend with --am Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 13/15] rebase tests: repeat some tests using the merge backend instead of am Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 14/15] rebase: make the backend configurable via config setting Elijah Newren via GitGitGadget 2019-12-23 18:49 ` [PATCH v2 15/15] rebase: change the default backend from "am" to "merge" Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 00/15] rebase: make the default backend configurable Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 01/15] rebase: extend the options for handling of empty commits Elijah Newren via GitGitGadget 2020-01-07 14:37 ` Phillip Wood 2020-01-07 19:15 ` Elijah Newren 2020-01-08 14:27 ` Phillip Wood 2020-01-09 21:32 ` Johannes Schindelin 2019-12-24 19:54 ` [PATCH v3 02/15] t3406: simplify an already simple test Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 03/15] rebase, sequencer: remove the broken GIT_QUIET handling Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 04/15] rebase: make sure to pass along the quiet flag to the sequencer Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 05/15] rebase: fix handling of restrict_revision Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 06/15] t3432: make these tests work with either am or merge backends Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 07/15] rebase: allow more types of rebases to fast-forward Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 08/15] git-rebase.txt: add more details about behavioral differences of backends Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 09/15] rebase: move incompatibility checks between backend options a bit earlier Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 10/15] rebase: add an --am option Elijah Newren via GitGitGadget 2020-01-07 14:43 ` Phillip Wood 2020-01-07 19:26 ` Elijah Newren 2020-01-07 20:11 ` Junio C Hamano 2020-01-08 14:32 ` Phillip Wood 2020-01-08 17:18 ` Junio C Hamano 2020-01-08 18:55 ` Phillip Wood 2019-12-24 19:54 ` [PATCH v3 11/15] git-prompt: change the prompt for interactive-based rebases Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 12/15] rebase tests: mark tests specific to the am-backend with --am Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 13/15] rebase tests: repeat some tests using the merge backend instead of am Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 14/15] rebase: make the backend configurable via config setting Elijah Newren via GitGitGadget 2019-12-24 19:54 ` [PATCH v3 15/15] rebase: change the default backend from "am" to "merge" Elijah Newren via GitGitGadget 2020-01-10 23:14 ` Jonathan Nieder 2020-01-11 1:16 ` Elijah Newren 2020-01-11 14:41 ` Phillip Wood 2020-01-12 17:59 ` Johannes Schindelin 2020-01-16 6:32 ` Elijah Newren 2020-01-16 7:58 ` Jonathan Nieder 2020-01-16 8:06 ` Jonathan Nieder 2020-01-16 16:18 ` Elijah Newren 2020-01-16 20:35 ` Jonathan Nieder 2020-01-16 21:30 ` Elijah Newren 2020-01-16 22:39 ` Jonathan Nieder 2020-01-16 23:19 ` Elijah Newren 2020-01-16 23:25 ` Junio C Hamano 2020-01-17 0:51 ` Elijah Newren 2020-01-16 15:35 ` Elijah Newren 2020-01-16 20:05 ` Junio C Hamano 2020-01-16 10:48 ` Johannes Schindelin 2020-01-12 21:23 ` Junio C Hamano 2020-01-15 19:50 ` Jonathan Nieder 2020-01-15 21:59 ` Emily Shaffer 2020-01-16 6:14 ` [PATCH v4 00/19] rebase: make the default backend configurable Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 01/19] git-rebase.txt: update description of --allow-empty-message Elijah Newren via GitGitGadget 2020-02-09 15:59 ` Phillip Wood 2020-02-13 18:35 ` Elijah Newren 2020-01-16 6:14 ` [PATCH v4 02/19] t3404: directly test the behavior of interest Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 03/19] rebase (interactive-backend): make --keep-empty the default Elijah Newren via GitGitGadget 2020-02-09 15:59 ` Phillip Wood 2020-02-13 18:52 ` Elijah Newren 2020-01-16 6:14 ` [PATCH v4 04/19] rebase (interactive-backend): fix handling of commits that become empty Elijah Newren via GitGitGadget 2020-02-10 14:27 ` Phillip Wood 2020-02-13 18:54 ` Elijah Newren 2020-02-16 14:46 ` Phillip Wood 2020-01-16 6:14 ` [PATCH v4 05/19] t3406: simplify an already simple test Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 06/19] rebase, sequencer: remove the broken GIT_QUIET handling Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 07/19] rebase: make sure to pass along the quiet flag to the sequencer Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 08/19] rebase: fix handling of restrict_revision Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 09/19] t3432: make these tests work with either am or merge backends Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 10/19] rebase: allow more types of rebases to fast-forward Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 11/19] git-rebase.txt: add more details about behavioral differences of backends Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 12/19] rebase: move incompatibility checks between backend options a bit earlier Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 13/19] rebase: add an --am option Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 14/19] git-prompt: change the prompt for interactive-based rebases Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 15/19] rebase: drop '-i' from the reflog " Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 16/19] rebase tests: mark tests specific to the am-backend with --am Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 17/19] rebase tests: repeat some tests using the merge backend instead of am Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 18/19] rebase: make the backend configurable via config setting Elijah Newren via GitGitGadget 2020-01-16 6:14 ` [PATCH v4 19/19] rebase: change the default backend from "am" to "merge" Elijah Newren via GitGitGadget 2020-01-17 16:58 ` [PATCH v4 00/19] rebase: make the default backend configurable Phillip Wood 2020-02-05 21:06 ` Junio C Hamano 2020-02-05 22:38 ` Elijah Newren 2020-02-15 21:36 ` [PATCH v5 00/20] rebase: make the default backend configurable and change the default Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 01/20] git-rebase.txt: update description of --allow-empty-message Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 02/20] t3404: directly test the behavior of interest Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 03/20] rebase (interactive-backend): make --keep-empty the default Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 04/20] rebase (interactive-backend): fix handling of commits that become empty Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 05/20] t3406: simplify an already simple test Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 06/20] rebase, sequencer: remove the broken GIT_QUIET handling Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 07/20] rebase: make sure to pass along the quiet flag to the sequencer Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 08/20] rebase: fix handling of restrict_revision Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 09/20] t3432: make these tests work with either am or merge backends Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 10/20] rebase: allow more types of rebases to fast-forward Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 11/20] git-rebase.txt: add more details about behavioral differences of backends Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 12/20] rebase: move incompatibility checks between backend options a bit earlier Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 13/20] rebase: add an --am option Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 14/20] git-prompt: change the prompt for interactive-based rebases Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 15/20] rebase: drop '-i' from the reflog " Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 16/20] rebase tests: mark tests specific to the am-backend with --am Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 17/20] rebase tests: repeat some tests using the merge backend instead of am Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 18/20] rebase: make the backend configurable via config setting Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 19/20] rebase: change the default backend from "am" to "merge" Elijah Newren via GitGitGadget 2020-02-15 21:36 ` [PATCH v5 20/20] rebase: rename the two primary rebase backends Elijah Newren via GitGitGadget 2020-03-12 15:13 ` Emily Shaffer 2020-03-12 16:33 ` Elijah Newren 2020-03-12 17:55 ` Jonathan Nieder 2020-03-12 18:39 ` Elijah Newren 2020-03-12 18:46 ` Jonathan Nieder 2020-03-12 19:31 ` Elijah Newren 2020-03-17 2:58 ` Jonathan Nieder 2020-03-17 4:45 ` Elijah Newren 2020-03-12 19:54 ` Junio C Hamano 2020-03-12 19:07 ` Junio C Hamano 2020-03-12 19:12 ` Jonathan Nieder 2020-03-12 19:12 ` Junio C Hamano 2020-03-12 19:29 ` Elijah Newren 2020-03-12 20:37 ` Jeff King 2020-03-12 21:27 ` Junio C Hamano 2020-03-12 22:06 ` Elijah Newren 2020-03-13 0:04 ` Junio C Hamano 2020-03-12 23:30 ` Jonathan Nieder 2020-02-16 15:01 ` [PATCH v5 00/20] rebase: make the default backend configurable and change the default Phillip Wood
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 * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=b307340f7c79c87b2b5a5a2a25d98ef68be4ba4f.1577127000.git.gitgitgadget@gmail.com \ --to=gitgitgadget@gmail.com \ --cc=Johannes.Schindelin@gmx.de \ --cc=alban.gruin@gmail.com \ --cc=git@vger.kernel.org \ --cc=gitster@pobox.com \ --cc=liu.denton@gmail.com \ --cc=newren@gmail.com \ --cc=phillip.wood@dunelm.org.uk \ --cc=plroskin@gmail.com \ --cc=szeder.dev@gmail.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
Git Mailing List Archive on lore.kernel.org Archives are clonable: git clone --mirror https://lore.kernel.org/git/0 git/git/0.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 git git/ https://lore.kernel.org/git \ git@vger.kernel.org public-inbox-index git Example config snippet for mirrors Newsgroup available over NNTP: nntp://nntp.lore.kernel.org/org.kernel.vger.git AGPL code for this site: git clone https://public-inbox.org/public-inbox.git