Re: [PATCH] Re: Clarify documentation on the "ours" merge strategy.

From: Thomas Rast <trast@student.ethz.ch>
Date: Nov 11, 2009, 23:37 UTC
Message-ID: <200911120037.11901.trast@student.ethz.ch>
In-Reply-To: <20091111213049.GJ27518@vidovic>

Nicolas Sebrecht wrote:

Show 12 quoted lines

> The 11/11/09, Junio C Hamano wrote:
> > Thomas Rast <trast@student.ethz.ch> writes:
> > 
> > > ++
> > > +Because the sides in a rebase are swapped, using this strategy with
> > > +git-rebase is never a good idea.
> > 
> > Looking very good.
> 
> If this strategy is _never_ a good idea in this case, I tend to think
> that git should forbid this option, or at least, warn and refer to the
> documentation.

Then again, I'm not sure if resolve vs. recursive makes a difference in a rebase. Octopus is weird for a two-head merge, I'm not sure why the docs even talk about it. That would leave only subtree, which indeed has its uses. Should we add a note to that effect to git-rebase.txt? Like, say,

diff --git i/Documentation/git-rebase.txt w/Documentation/git-rebase.txt
index 33e0ef1..6e54a57 100644
--- i/Documentation/git-rebase.txt
+++ w/Documentation/git-rebase.txt
@@ -228,13 +228,19 @@ 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 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>.
 
 -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.
++
+Due to the peculiarities of 'git-rebase' (see \--merge above) the only
+built-in strategy that is actually useful is 'subtree'.
 
 -q::
 --quiet::
diff --git i/Documentation/merge-strategies.txt w/Documentation/merge-strategies.txt
index 4365b7e..c1c3add 100644
--- i/Documentation/merge-strategies.txt
+++ w/Documentation/merge-strategies.txt
@@ -33,6 +33,9 @@ ours::
 	merge is always the current branch head.  It is meant to
 	be used to supersede old development history of side
 	branches.
++
+Because the sides in a rebase are swapped, using this strategy with
+'git-rebase' is never a good idea.
 
 subtree::
 	This is a modified recursive strategy. When merging trees A and

-- 
Thomas Rast
trast@{inf,student}.ethz.ch