[v3] merge-options.txt: clarify meaning of various ff-related options
diff mbox series

Message ID 20190828225712.20041-1-newren@gmail.com
State New
Headers show
Series
  • [v3] merge-options.txt: clarify meaning of various ff-related options
Related show

Commit Message

Elijah Newren Aug. 28, 2019, 10:57 p.m. UTC
As discovered on the mailing list, some of the descriptions of the
ff-related options were unclear.  Try to be more precise with what these
options do.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
Changes since v2:
  * reordered the options
  * typeset the option flags differently to ensure they are monospace in
    the rendered documentation

 Documentation/merge-options.txt | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

Comments

Junio C Hamano Aug. 30, 2019, 7:57 p.m. UTC | #1
Elijah Newren <newren@gmail.com> 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.

Thanks.
Eric Sunshine Aug. 30, 2019, 8:16 p.m. UTC | #2
On Fri, Aug 30, 2019 at 3:57 PM Junio C Hamano <gitster@pobox.com> wrote:
> 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.

I have not been paying close attention to this thread, but upon
reading your suggested rewrites, I find the lighter paragraph (the
first of your options), followed by the three short paragraphs -- each
dedicated to a distinct option -- easier to follow and grok. I think
that's because the lighter/shorter arrangement keeps the three cases
reasonably separate -- thus the reader is able to absorb and
understand each distinct option in isolation -- rather than having to
manually pluck out the meaning of each option from one long, run-on
sentence.

Patch
diff mbox series

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::
-	When the merge resolves as a fast-forward, only update the branch
-	pointer, without creating a merge commit.  This is the default
-	behavior.
-
 --no-ff::
-	Create a merge commit even when the merge resolves as a
-	fast-forward.  This is the default behaviour when merging an
-	annotated (and possibly signed) tag that is not stored in
-	its natural place in 'refs/tags/' hierarchy.
-
 --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.
+	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.
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::