mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Sergey Organov <>
To: "Martin Ågren" <>
Cc: Elijah Newren <>,
	Junio C Hamano <>,
	Git Mailing List <>
Subject: Re: [PATCH v2] merge-options.txt: clarify meaning of various ff-related options
Date: Thu, 29 Aug 2019 12:35:07 +0300	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <> ("Martin \=\?utf-8\?Q\?\=C3\=85gren\=22's\?\= message of "Wed, 28 Aug 2019 21:53:47 +0200")

Martin Ågren <> writes:

> Hiya,

This one was new to me :-)

> On Wed, 28 Aug 2019 at 21:15, Sergey Organov <> wrote:
>> > 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.
>> 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.
> I think this could make clear that the first paragraph talks about
> `--ff`. I know that we often list `--foo` and `--no-foo`, say "This
> option does bar" and leave it to the reader to figure out which is which.
> Most of the time, that's fairly obvious though (foo=bar). With this
> tri-state option, we might be past the point of fair obviousness.
> Then again, seeing "ff" and "fast forward", it's not /that hard/ to
> figure out.

Yeah, I've noticed that myself, but decided to keep it, as this was
meant to be a quick re-arrangement of already existing description, and
be as short as at all possible, as lengthy descriptions tend to obscure

Being this way it shows how difficult it is to document flawed design. I
guess the author of --ff-only would think twice should --ff/--no-ff be
originally documented similarly to the rest of 2-way options. At least
he'd likely call it --only-ff, as:


looks much better. Yeah, I do realize all this is historical and such...

> Apart from that, this reads well. Of course with the usual caveat of
> the topic being fresh on my mind, so in general, I'd be more likely to
> understand what it is I'm reading. ;-)

... and I'm in even worse position here ;-)


  reply	other threads:[~2019-08-29  9:35 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-08-28  0:13 [PATCH] merge-options.txt: clarify meaning of various ff-related options Elijah Newren
2019-08-28  9:05 ` Sergey Organov
2019-08-28 15:51   ` [PATCH v2] " Elijah Newren
2019-08-28 18:45     ` Martin Ågren
2019-08-28 19:15       ` Sergey Organov
2019-08-28 19:53         ` Martin Ågren
2019-08-29  9:35           ` Sergey Organov [this message]
2019-08-28 22:51         ` Elijah Newren
2019-08-29  9:15           ` Sergey Organov
2019-08-28 22:57       ` [PATCH v3] " Elijah Newren
2019-08-30 19:57         ` Junio C Hamano
2019-08-30 20:16           ` Eric Sunshine
2019-08-31  0:23             ` [PATCH v4] " Elijah Newren
2019-08-30 19:45       ` [PATCH v2] " Junio C Hamano
2019-08-30 19:48         ` Elijah Newren
2019-08-30 20:27           ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).