From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 16 Apr 2021 19:11:57 GMT
Subject: Re: [PATCH v10 1/2] [GSOC] docs: correct descript of trailer.<token>.command
Message-ID: <xmqq7dl2m4ci.fsf@gitster.g>
In-Reply-To: <8129ef6c476b4f35be59eae71367de5b83888068.1618562875.git.gitgitgadget@gmail.com>

"ZheNing Hu via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Subject: Re: [PATCH v10 1/2] [GSOC] docs: correct descript of trailer.<token>.command

s/descript/&ion/ (no need to resend only to fix this).

> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index 96ec6499f001..6f2a7a130464 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -232,25 +232,30 @@ trailer.<token>.ifmissing::
>  	that option for trailers with the specified <token>.
>  
>  trailer.<token>.command::
> +	This option can be used to specify a shell command that will be called:
> +	once to automatically add a trailer with the specified <token>, and then
> +	each time a '--trailer <token>=<value>' argument to modify the <value> of
> +	the trailer that this option would produce.
>  +
> +When the specified command is first called to add a trailer
> +with the specified <token>, the behavior is as if a special
> +'--trailer <token>=<value>' argument was added at the beginning
> +of the "git interpret-trailers" command, where <value>
> +is taken to be the standard output of the command with any
> +leading and trailing whitespace trimmed off.
>  +
> +If some '--trailer <token>=<value>' arguments are also passed
> +on the command line, the command is called again once for each
> +of these arguments with the same <token>. And the <value> part
> +of these arguments, if any, will be used to replace the first
> +occurrence of substring `$ARG` in the command. This way the
> +command can produce a <value> computed from the <value> passed
> +in the '--trailer <token>=<value>' argument.
>  +

Makes quite a lot of sense.  I wouldn't have got confused by the
behaviour of .command if it were documented like the above from day
one.  Very nice.

> +For consistency, the first occurrence of substring `$ARG` is
> +also replaced, this time with the empty string, in the command
> +when the command is first called to add a trailer with the
> +specified <token>.

OK, so "for consistency" is about consistency between the "execute
once first without being asked" case (where there is no plausible
source of $ARG), and "execute because we were asked by a command
line option (where we are given <value> to replace $ARG).

Makes sense.

Will queue.  Thanks.