Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command

[Junio C Hamano <gitster@pobox.com>]

pvutov@imap.cc writes:

> From: Petar Vutov <pvutov@imap.cc>
>
> Bugfix for fc01a5d2 (submodule update documentation: don't repeat
> ourselves, 2016-12-27).
>
> The `custom command` and `none` entries are described as sharing the
> same limitations, but one is allowed in .gitmodules and the other is
> not. Instead, describe their limitations separately and in slightly
> more detail.

Sounds sensible.

>
> Signed-off-by: Petar Vutov <pvutov@imap.cc>
> ---
>
> Changes from v1:
> Don't delete the documentation for `!command`. Instead, highlight
> the differences in the limitations of `none` and `!command`.
>
> Changes from v2:
> Improve phrasing.
> Add the bugfix blurb in the commit message.
>
>  Documentation/git-submodule.txt | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 4d3ab6b9f9..69ee2cd6b0 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -160,16 +160,19 @@ checked out in the submodule.
>  	merge;; the commit recorded in the superproject will be merged
>  	    into the current branch in the submodule.
>  
> -The following 'update' procedures are only available via the
> -`submodule.<name>.update` configuration variable:
> -
>  	custom command;; arbitrary shell command that takes a single
>  	    argument (the sha1 of the commit recorded in the
>  	    superproject) is executed. When `submodule.<name>.update`
>  	    is set to '!command', the remainder after the exclamation mark
>  	    is the custom command.
> ++
> +Custom commands are only allowed in the `submodule.<name>.update`
> +git-config variable. They cannot be used in the .gitmodules file.
>  
>  	none;; the submodule is not updated.
> ++
> +The `none` update procedure is allowed in the .gitmodules file
> +or the `submodule.<name>.update` git-config variable.

But the usual ones like "merge" are also allowed in both places.
Does this still need to be said?

I wonder if it makes more sense to swap the order of these two
entries, showing "none" without any additional text first, and
then describe "custom command" with the note, exactly like you
did above.