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

> I applied your patch and then made some additions, which I'll append
> at the end of this message. Summary:
>
> * Added your rewrite from yesterday. I like that it's more precise
>   than the current docs, but I struggle with the complexity of the
>   first sentence. I wanted to make it easier to follow by splitting it
>   in two somehow. Instead I ended up with an introductory sentence
>   summarizing the functionality with small words.
>
> * In gitmodules.txt, moved the security disclaimer so people are more
>   likely to see it before they follow the link to git-submodule.txt.
>
> * Explicitly called out `none` and `custom command` as being unusable
>   on the command line (and in .gitmodules). I expect that you won't
>   want that .gitmodules mention anymore, but I left it in for now, up
>  to you.
>
> The diff below is based on top of your patch from yesterday, since I
> assume that you don't want to look at a mishmash of both patches.

> diff --git a/Documentation/git-submodule.txt
> b/Documentation/git-submodule.txt
> index 5248840b18..695730609a 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -165,13 +165,18 @@ checked out in the submodule.
>  	merge;; the commit recorded in the superproject will be merged
>  	    into the current branch in the submodule.
>
> -	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.
> -
> -	none;; the submodule is not updated.
> +The following update procedures have additional limitations:
> +
> +	custom command;; mechanism for running arbitrary commands with the
> +	    commit ID as an argument. Specifically, if the
> +	    `submodule.<name>.update` configuration variable is set to
> +	    `!custom command`, the object name of the commit recorded in the
> +	    superproject for the submodule is appended to the `custom command`
> +	    string and executed. Note that this mechanism is not supported in
> +	    the `.gitmodules` file or on the command line.
> +
> +	none;; the submodule is not updated. This update procedure is not
> +	    allowed on the command line.
>
>  If the submodule is not yet initialized, and you just want to use the
>  setting as stored in `.gitmodules`, you can automatically initialize the
> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
> index dcee09b500..d9bec8b187 100644
> --- a/Documentation/gitmodules.txt
> +++ b/Documentation/gitmodules.txt
> @@ -43,9 +43,9 @@ submodule.<name>.update::
>  	command in the superproject. This is only used by `git
>  	submodule init` to initialize the configuration variable of
>  	the same name. Allowed values here are 'checkout', 'rebase',
> -	'merge' or 'none'. See description of 'update' command in
> -	linkgit:git-submodule[1] for their meaning. For security
> -	reasons, the '!command' form is not accepted here.
> +	'merge' or 'none', but not '!command' (for security reasons).
> +	See the description of the 'update' command in
> +	linkgit:git-submodule[1] for more details.
>
>  submodule.<name>.branch::
>  	A remote branch name for tracking updates in the upstream submodule.