docs: correct descript of trailer.<token>.command
In the original documentation of `trailer.<token>.command`, some descriptions are easily misunderstood. So let's modify it to increase its readability. In addition, clarify that `$ARG` in command can only be replaced once. Signed-off-by: ZheNing Hu <adlternative@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
ZheNing Hu committed
May 3, 2021 at 15:41 UTC
57dcb6575b577a70f02814df4291e8af6ed81f86
1 file changed
+21
-16
Documentation/git-interpret-trailers.txt
+21
-16
@@ -232,25 +232,30 @@ trailer.<token>.ifmissing::
232
that option for trailers with the specified <token>.
233
234
trailer.<token>.command::
235
- This option can be used to specify a shell command that will
236
- be called to automatically add or modify a trailer with the
237
- specified <token>.
235
+ This option can be used to specify a shell command that will be called:
236
+ once to automatically add a trailer with the specified <token>, and then
237
+ each time a '--trailer <token>=<value>' argument to modify the <value> of
238
+ the trailer that this option would produce.
239
+
239
-When this option is specified, the behavior is as if a special
240
-'<token>=<value>' argument were added at the beginning of the command
241
-line, where <value> is taken to be the standard output of the
242
-specified command with any leading and trailing whitespace trimmed
243
-off.
240
+When the specified command is first called to add a trailer
241
+with the specified <token>, the behavior is as if a special
242
+'--trailer <token>=<value>' argument was added at the beginning
243
+of the "git interpret-trailers" command, where <value>
244
+is taken to be the standard output of the command with any
245
+leading and trailing whitespace trimmed off.
246
+
245
-If the command contains the `$ARG` string, this string will be
246
-replaced with the <value> part of an existing trailer with the same
247
-<token>, if any, before the command is launched.
247
+If some '--trailer <token>=<value>' arguments are also passed
248
+on the command line, the command is called again once for each
249
+of these arguments with the same <token>. And the <value> part
250
+of these arguments, if any, will be used to replace the first
251
+occurrence of substring `$ARG` in the command. This way the
252
+command can produce a <value> computed from the <value> passed
253
+in the '--trailer <token>=<value>' argument.
254
+
249
-If some '<token>=<value>' arguments are also passed on the command
250
-line, when a 'trailer.<token>.command' is configured, the command will
251
-also be executed for each of these arguments. And the <value> part of
252
-these arguments, if any, will be used to replace the `$ARG` string in
253
-the command.
255
+For consistency, the first occurrence of substring `$ARG` is
256
+also replaced, this time with the empty string, in the command
257
+when the command is first called to add a trailer with the
258
+specified <token>.
259
260
EXAMPLES
261
--------