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

From: Sergey Organov <sorganov@gmail.com>
Date: Aug 28, 2019, 19:15 UTC
Message-ID: <87a7btqeyx.fsf@osv.gnss.ru>
In-Reply-To: <CAN0heSoqy4sCY8NUWKuEkXwe2XxnYAN6Mn2N75hYwfQ_5WGYdQ@mail.gmail.com>

Hi,

Martin Ågren <martin.agren@gmail.com> writes:

[...]

Show 28 quoted lines

>> ++
>> +With --ff-only, resolve the merge as a fast-forward when possible
>> +(when the merged branch contains the current branch in its history).
>> +When not possible, refuse to merge and exit with a non-zero status.
>> ++
>> +With --no-ff, create a merge commit in all cases, even when the merge
>> +could instead resolve as a fast-forward.
>> ++
>> +With --ff, resolve the merge as a fast-forward when possible.  When not
>> +possible, create a merge commit.
>>
>> ---ff-only::
>> -       Refuse to merge and exit with a non-zero status unless the
>> -       current `HEAD` is already up to date or the merge can be
>> -       resolved as a fast-forward.
>
> I was sort of expecting these to be listed in the order "--ff, --no-ff,
> --ff-only", and I see Sergey suggested the same ordering. The way your
> proposed text reads does make sense though... Would it read as well
> turning it over and going through the options in the other order? That's
> the way it is before your patch, so you could argue "but people don't
> grok that!". What your patch does well is to offer an overview before
> describing each option in a bit more detail. Would that work with the
> reversed direction as well (compared to this patch)? Dunno.
>
> I wondered briefly whether it might make sense to float "The default is
> `--no-ff`." to the top, but since it's really "The default ... unless
> so-and-so", it would probably complicate things more than it'd help.

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
	branch pointer (without creating a merge commit).  When a fast
	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.
+
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.

-- 
Sergey