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

Elijah Newren <> writes:

> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index 79a00d2a4a..ed3804650b 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -40,20 +40,26 @@ set to `no` at the beginning of them.
>  	case of a merge conflict.
>  --ff::
>  --no-ff::
>  --ff-only::
> +	Whether to prefer resolving the merge as a fast forward (only
> +	updating the branch pointer to match the merged branch and not
> +	creating a merge commit), to never allow it (always creating a
> +	merge commit), or to only allow fast forward updates.  The
> +	default is `--ff`, except when merging an annotated (and
> +	possibly signed) tag that is not stored in its natural place
> +	in the `refs/tags/` hierarchy (in which case `--no-ff` is
> +	assumed).
> ++
> +With `--ff`, resolve the merge as a fast-forward when possible (when the
> +merged branch contains the current branch in its history).  When not
> +possible, create a merge commit.
> ++
> +With `--no-ff`, create a merge commit in all cases, even when the merge
> +could instead be resolved as a fast-forward.
> ++
> +With `--ff-only`, resolve the merge as a fast-forward when possible.
> +When not possible, refuse to merge and exit with a non-zero status.

I cannot shake the feeling that the above redundantly repeats the
same thing twice.

If we want to dedicate one paragraph for each of these options, we
can and should make the introductory paragraph lighter by saying
something like

	Specifies how a merge is handled when the merged-in history
	is already a descendant of the current history.  `--ff` is
	the default unless merging an annotated or signed tag that
	is not stored in the `refs/tags/` hierarchy, in which case
	`--no-ff` is the default.

Alternatively, we could sprinkle the actual option name in the first
paragraph and drop the last three paragraphs, while fattening the
description as necessary, e.g.

	Whether to prefer resolving the merge as a fast-forward and
	update the branch pointer to match the merged branch without
	creating an extra merge commit (`--ff`), never allow fast-forward
	and always creating an extra merge commit (`--no-ff`), or to
	only allow fast forward updates and reject when a merge
	commit needs to be created (`--ff-only`).  The default is ...

I think either approach shown above would reduce the redundancy.  I
do not care too deeply which one of these approaches is used myself,
but the redundancy feels a bit disturbing.


  reply	other threads:[~2019-08-30 19:57 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
2019-08-29  9:15           ` Sergey Organov
2019-08-28 22:57       ` [PATCH v3] " Elijah Newren
2019-08-30 19:57         ` Junio C Hamano [this message]
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).