Re: [PATCH 2/3] rebase docs: clarify --merge and --strategy
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:47:43
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Thomas Rast [off-list ref] writes:
Add a paragraph about the swapped sides in a --merge rebase, which was otherwise only documented in the sources. Add a paragraph about the effects of the 'ours' strategy to the -s description. Also remove the mention of the 'octopus' strategy, which was copied from the git-merge description but is pointless in a rebase.
Instead of saying "peculiarities" without saying what is peculiar about it, it might be better to give an explanation that would help the reader understand why they appear "swapped". Here is my attempt. Thoughts? Documentation/git-rebase.txt | 12 ++++++++---- 1 files changed, 8 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index e802421..a6f8182 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt@@ -229,9 +229,11 @@ OPTIONS strategy is used, this allows rebase to be aware of renames on the upstream side. + -Note that in a rebase merge (hence merge conflict), the sides are -swapped: "theirs" is the to-be-applied patch, and "ours" is the so-far -rebased series, starting with <upstream>. +Note that a rebase merge works by replaying each commit from the working +branch on top of the <upstream> branch. Because of this, when a merge +conflict happens, the side reported as 'ours' is the so-far rebased +series, starting with <upstream>, and 'theirs' is the working branch. In +other words, the sides are swapped. -s <strategy>:: --strategy=<strategy>::
@@ -239,7 +241,9 @@ rebased series, starting with <upstream>. If there is no `-s` option 'git-merge-recursive' is used instead. This implies --merge. + -Due to the peculiarities of 'git-rebase' (see \--merge above), using +Because 'git-rebase' replays each commit from the working branch +on top of the <upstream> branch using the given strategy, +(see \--merge above), using the 'ours' strategy simply discards all patches from the <branch>, which makes little sense. Thus 'git-rebase' does not accept this strategy.