mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Elijah Newren <>
To: Sergey Organov <>
Cc: "Martin Ågren" <>,
	"Junio C Hamano" <>,
	"Git Mailing List" <>
Subject: Re: [PATCH v2] merge-options.txt: clarify meaning of various ff-related options
Date: Wed, 28 Aug 2019 15:51:14 -0700	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

On Wed, Aug 28, 2019 at 12:15 PM Sergey Organov <> 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.

  parent reply	other threads:[~2019-08-28 22:51 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
2019-08-28 22:51         ` Elijah Newren [this message]
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).