From: Baz <brian.ewins@gmail.com>
Date: Wed, 11 Nov 2009 20:54:54 GMT
Subject: Re: [PATCH] Clarify documentation on the "ours" merge strategy.
Message-ID: <2faad3050911111254h426e24ccg93d2824f9e971521@mail.gmail.com>
In-Reply-To: <200911112135.25839.trast@student.ethz.ch>

2009/11/11 Thomas Rast <trast@student.ethz.ch>:
> Baz wrote:
>> 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.
> [...]
>> 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.

Yes, this (with Peter's patch) makes the danger nice & clear.

Thanks!

-Baz

>
>  subtree::
>        This is a modified recursive strategy. When merging trees A and
>
> --
> Thomas Rast
> trast@{inf,student}.ethz.ch
>