Re: [PATCH 2/3] rebase docs: clarify --merge and --strategy

From

Junio C Hamano <gitster@pobox.com>

Date

Nov 15, 2009, 21:05 UTC

Message-ID

<7v7htrfqi1.fsf@alter.siamese.dyndns.org>

In-Reply-To

<b7f805f2497d748b685544b64cd91a36c3bdf5d6.1258309432.git.trast@student.ethz.ch>

Thomas Rast <trast@student.ethz.ch> 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.

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.