Elijah Newren <newren@xxxxxxxxx> 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@xxxxxxxxx>
> ---
> 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
