Re: [PATCH v2] merge-options.txt: clarify meaning of various ff-related options

[Sergey Organov <sorganov@gmail.com>]

Elijah Newren <newren@gmail.com> writes:

> On Wed, Aug 28, 2019 at 12:15 PM Sergey Organov <sorganov@gmail.com> wrote:
>>
>> Hi,
>>
> [...]
>> Dunno if it helps, but here is what I came up with somewhere in previous
>> discussions:
>>
>> --ff::
>> --no-ff::
>> --ff-only::
>>         When the merge resolves as a fast-forward, only update the
>
> I think this loose wording (that you just took from the original) is
> problematic.  Saying that a "merge resolves as a fast-forward" seems
> to imply that there are circumstances when a fast-forward is the only
> option.  An _individual_ can decide to resolve a merge as a
> fast-forward in some circumstances, but it's certainly not the only
> choice in any circumstance.  If you want to keep this wording short,
> you could replace "resolves" with "can be resolved".
>
>>         branch pointer (without creating a merge commit).  When a fast
>
> Only update the branch pointer to what?  (Yes, I know the original
> text we were improving left this unclear, but it's worth noting.)
>
>>         forward update is not possible, create a merge commit.  This is
>>         the default behavior, unless merging an annotated (and possibly
>>         signed) tag that is not stored in its natural place in
>>         'refs/tags/' hierarchy, in which case --no-ff is assumed.
>
> Maybe it's just me, but I think it takes extra human cycles to figure
> out that this paragraph is referring just to the --ff case, and that
> users might not be able to do so until after reading the next 2-3
> sentences.  While more brief, I think it will cause people to need to
> read the description for these three options twice, removing most the
> savings from being shorter.  It'd be better if it could be re-worded
> to not need re-reads.
>
>> +
>> With --no-ff create a merge commit even when the merge could instead
>> resolve as a fast-forward.
>> +
>> With --ff-only resolve the merge as a fast-forward (never create a merge
>> commit). When fast-forward is not possible, refuse to merge and exit
>> with non-zero status.
>
> Something else I was trying to address with my patch that perhaps you
> can see a different way to tackle: Using the wording "when possible"
> is probably going to make users wonder when a fast forward is
> possible; the "can be resolved" wording tweak also makes it more
> likely they will wonder about this.  Another question they will be
> wondering about is what a fast forward is (which you partially
> explain).  Some basic knowledge of both are probably very useful in
> helping them decide which option to actually pick.  As such, I think
> trying to explain the answers to these sub-questions will assist them
> in knowing which option to use.  Simply inserting a couple phrases
> (e.g. "when the merged branch contains the current branch in its
> history", and "only update the branch pointer *to match the merged
> branch* and do not create a merge commit") may help a lot.
>
> Anyway, I'll send a v3 addressing Martin's comments; if you've got
> further suggestions for streamlining or rearranging, though, please do
> send them along.

Thanks for thorough reply!

My version was meant to show how to re-arrange the description
preserving original wording as much as possible, so your version should
be better, as it addresses other problems as well.

-- 
Sergey