rebase docs: clarify --merge and --strategy

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.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 0aefc34d0d311030687563c56eaf3ac85a687e28..167c8bed599b525c2ddb64093a74e6fe41b09b10 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -228,13 +228,23 @@ OPTIONS
        Use merging strategies to rebase.  When the recursive (default) merge
        strategy is used, this allows rebase to be aware of renames on the
        upstream side.
++
+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>::
        Use the given merge strategy.
-       If there is no `-s` option, a built-in list of strategies
-       is used instead ('git-merge-recursive' when merging a single
-       head, 'git-merge-octopus' otherwise).  This implies --merge.
+       If there is no `-s` option 'git-merge-recursive' is used
+       instead.  This implies --merge.
++
+Because 'git-rebase' replays each commit from the working branch
+on top of the <upstream> branch using the given strategy, using
+the 'ours' strategy simply discards all patches from the <branch>,
+which makes little sense.
 
 -q::
 --quiet::