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@xxxxxxxxx>
---
Changes since v1:
* Grouped much like --option/--no-option items are to make it clearer
that these are related options, as suggested by Sergey.
Documentation/merge-options.txt | 33 ++++++++++++++++++++-------------
1 file changed, 20 insertions(+), 13 deletions(-)
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index 79a00d2a4a..348d66f54b 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -39,21 +39,28 @@ set to `no` at the beginning of them.
to `MERGE_MSG` before being passed on to the commit machinery in the
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.
-
+--ff-only::
--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::
+ Whether to only allow 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 prefer it when possible. The
+ default is --ff, except when 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 the
+ default).
++
+With --ff-only, resolve the merge as a fast-forward when possible
+(when the merged branch contains the current branch in its history).
+When not possible, refuse to merge and exit with a non-zero status.
++
+With --no-ff, create a merge commit in all cases, even when the merge
+could instead resolve as a fast-forward.
++
+With --ff, resolve the merge as a fast-forward when possible. When not
+possible, create a merge commit.
---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.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
--
2.23.0.9.g568fda2d03
