Merge branch 'tr/maint-merge-ours-clarification' (early part)

* 'tr/maint-merge-ours-clarification' (early part):
rebase docs: clarify --merge and --strategy
Documentation: clarify 'ours' merge strategy

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 33e0ef1f6d48c22eddb2b1a7273065a4269924ae..ca5e1e8653be7a1d2b0911ec572ff0a85300ebb9 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::

diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 4365b7e8420fa96d6cbfa14a5aa49d956ba2de16..42910a3d5e0229f471c5bceb0c36f184d17ebb08 100644 (file)
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -29,8 +29,9 @@ octopus::
        pulling or merging more than one branch.
 
 ours::
-       This resolves any number of heads, but the result of the
-       merge is always the current branch head.  It is meant to
+       This resolves any number of heads, but the resulting tree of the
+       merge is always that of the current branch head, effectively
+       ignoring all changes from all other branches.  It is meant to
        be used to supersede old development history of side
        branches.