Merge branch 'en/merge-options-ff-and-friends'

Doc update.

* en/merge-options-ff-and-friends:
merge-options.txt: clarify meaning of various ff-related options

diff --combined Documentation/merge-options.txt
index d6a9f4b96faaf2814b41a2ff79a49c9d4d899795,94be34f9412557a7d4d30c8a0bfff6aa63e2176b..59b8ff1e51a5e173c208d1c8cd7fab71dcf37a2e
--- 1/Documentation/merge-options.txt
--- 2/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@@ -40,20 -40,24 +40,24 @@@ 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.
+       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 (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`, when possible resolve the merge as a fast-forward (only
+ update the branch pointer to match the merged branch; do not create a
+ merge commit).  When not possible (when the merged-in history is not a
+ descendant of the current history), 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>]::
@@@ -105,10 -109,6 +109,10 @@@ option can be used to override --squash
  +
  With --squash, --commit is not allowed, and will fail.
  
 +--no-verify::
 +      This option bypasses the pre-merge and commit-msg hooks.
 +      See also linkgit:githooks[5].
 +
  -s <strategy>::
  --strategy=<strategy>::
        Use the given merge strategy; can be supplied more than