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

From: Thomas Rast <trast@student.ethz.ch>
Date: Nov 11, 2009, 20:35 UTC
Message-ID: <200911112135.25839.trast@student.ethz.ch>
In-Reply-To: <2faad3050911110713y4e33c7d2h21ad42efe4fd70b3@mail.gmail.com>

Baz wrote:

Show 10 quoted lines

> 2009/11/11 Peter Krefting <peter@softwolves.pp.se>:
> >  ours::
> >        This resolves any number of heads, but the result of the
> > -       merge is always the current branch head.  It is meant to
> > +       merge is always the current branch head, discarding any
> > +       changes on the merged branch.  It is meant to
> 
> I think part of the problem is that it is unclear what the "current
> branch head" means when used in a rebase, and hence when this text is
> included in the help for git-rebase and git-pull.

[...]

Show 11 quoted lines

> Perhaps something more in the way of an explicit warning?
> 
> ours::
>          This resolves any number of heads, but the result of the
>          merge is always the current branch head, discarding any
>          changes on the merged branch.  It is meant to
>          be used to supersede old development history of side
>          branches. Note that when rebasing, the branch you are
>          rebasing onto is the "current branch head", and using this
>          strategy will lose all of your changes - unlikely to be what
>          you wanted to do.

I'd much rather see this explained in the description of the rebase -m/-s options since it (the swap) applies to all uses of 'git rebase -m'. Perhaps with an extra (but short) note in the "ours" description, like so:

diff --git i/Documentation/git-rebase.txt w/Documentation/git-rebase.txt
index 33e0ef1..181947c 100644
--- i/Documentation/git-rebase.txt
+++ w/Documentation/git-rebase.txt
@@ -228,6 +228,10 @@ 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>::
diff --git i/Documentation/merge-strategies.txt w/Documentation/merge-strategies.txt
index 4365b7e..0cae1be 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