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

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

Commit Message

Elijah Newren Aug. 28, 2019, 12:13 a.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>
---
I noticed this patch sitting around in one of my branches, and noticed it
wasn't upstream.  I'm pretty sure I submitted it a few months back, but I
think it got lost in the cracks.  Resubmitting and I'll see if I can do a
better job following up on it.

 Documentation/merge-options.txt | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

Comments

Sergey Organov Aug. 28, 2019, 9:05 a.m. UTC | #1
Elijah Newren <newren@gmail.com> writes:

> 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>
> ---
> I noticed this patch sitting around in one of my branches, and noticed it
> wasn't upstream.  I'm pretty sure I submitted it a few months back, but I
> think it got lost in the cracks.  Resubmitting and I'll see if I can do a
> better job following up on it.
>
>  Documentation/merge-options.txt | 20 +++++++++++---------
>  1 file changed, 11 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index 79a00d2a4a..b39df5f126 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -40,20 +40,22 @@ 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
> +	When the merge can resolve as a fast-forward, do so (only
> +	update the branch pointer to match the merged branch; do not
> +	create a merge commit).  When a fast forward update is not
> +	possible, create 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.
> +	Create a merge commit even when the merge could instead resolve
> +	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.

Please notice that virtually all the other cases of
--something/--no-something are formatted like this:

--something::
--no-something::
        [descriptions]

So, even only for consistency, it seems to be better to have this the
same way:

  --ff::
  --no-ff::
  --ff-only::
        [descriptions]

that, as a bonus, will make it explicit and crystal clear that these 3
things are alternatives, and thus the last one on the command line takes
precedence.

-- Sergey

Patch
diff mbox series

diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index 79a00d2a4a..b39df5f126 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -40,20 +40,22 @@  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
+	When the merge can resolve as a fast-forward, do so (only
+	update the branch pointer to match the merged branch; do not
+	create a merge commit).  When a fast forward update is not
+	possible, create 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.
+	Create a merge commit even when the merge could instead resolve
+	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.
+	When possible, resolve the merge as a fast-forward (do not
+	create a merge commit).  When not possible, refuse to merge and
+	exit with a non-zero status.
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::