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.
        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.
 
 -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::
 
 -q::
 --quiet::