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

From: Petar Vutov <pvutov@imap.cc>
Date: Jul 13, 2023, 20:34 UTC
Message-ID: <9de918bc-6913-0486-02dd-5b4028a7fe1b@imap.cc>
In-Reply-To: <xmqqwmz3oacg.fsf@gitster.g>

On 7/13/23 21:55, Junio C Hamano wrote:

> Petar Vutov <pvutov@imap.cc> writes:
> 
> Don't.  People should be familiar with "configuration variable", but
> may not be with "git-config variable".

Right, on closer inspection this collision with .gitmodules is rather niche to start with. Few things in .gitconfig are also legal in .gitmodules.

Show 22 quoted lines

>   
> -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.
> -
>   	none;; the submodule is not updated.
>   
> +	custom command;; When 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 gets executed.  Note that this mechanism
> +	    cannot be used in the `.gitmodules` file.
> +
>   If the submodule is not yet initialized, and you just want to use the
>   setting as stored in `.gitmodules`, you can automatically initialize the
>   submodule with the `--init` option.

I prefer the original description as it uses shorter sentences. I can't hold that 5-liner in my head :)

But now I really am bikeshedding, and I've taken enough of your time. I will send a v4 with just the .gitmodules disclaimer, no rewrite, in case you end up agreeing.