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 <new...@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(-)

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>]::
-- 
2.23.0.3.g93492fb5e6.dirty

Reply via email to