[PATCH v9 0/2] [GSOC] trailer: add new .cmd config option

In https://lore.kernel.org/git/xmqqv99i4ck2.fsf@gitster.g/ Junio and Christian talked about the problem of using strbuf_replace() to replace $ARG:

 1. if the user's script has more than one $ARG, only the first one will be
    replaced, which is incorrected.
 2. $ARG is textually replaced without shell syntax, which may result a
    broken command when $ARG include some unmatching single quote, very
    unsafe.

Now pass trailer value as $1 to the trailer command with another trailer.<token>.cmd config, to solve these above two problems,

We are now writing documents that are more readable and correct than before.

ZheNing Hu (2):
  [GSOC] docs: correct descript of trailer.<token>.command
  [GSOC] trailer: add new .cmd config option

 Documentation/git-interpret-trailers.txt | 96 ++++++++++++++++++++----
 t/t7513-interpret-trailers.sh            | 84 +++++++++++++++++++++
 trailer.c                                | 37 ++++++---
 3 files changed, 190 insertions(+), 27 deletions(-)

base-commit: 142430338477d9d1bb25be66267225fb58498d92
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-913%2Fadlternative%2Ftrailer-pass-ARG-env-v9
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-913/adlternative/trailer-pass-ARG-env-v9
Pull-Request: https://github.com/gitgitgadget/git/pull/913

Range-diff vs v8:

 1:  505903811df8 ! 1:  8129ef6c476b [GSOC] docs: correct descript of trailer.<token>.command
     @@ Commit message
          it to increase its readability.
      
          In addition, clarify that `$ARG` in command can only be
     -    replaced once since `$ARG` is text replacement.
     +    replaced once.
      
          Signed-off-by: ZheNing Hu <adlternative@gmail.com>
      
       ## Documentation/git-interpret-trailers.txt ##
     -@@ Documentation/git-interpret-trailers.txt: trailer.<token>.command::
     - 	specified <token>.
     +@@ Documentation/git-interpret-trailers.txt: 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 to automatically add or modify a trailer with the
     +-	specified <token>.
     ++	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 this option is specified, the behavior is as if a special
     +-When this option is specified, the behavior is as if a special
      -'<token>=<value>' argument were added at the beginning of the command
      -line, where <value> is taken to be the standard output of the
      -specified command with any leading and trailing whitespace trimmed
      -off.
     -+'--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 specified command with any leading and trailing
     -+whitespace trimmed off.
     ++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 the command contains the `$ARG` string, this string will be
      -replaced with the <value> part of an existing trailer with the same
      -<token>, if any, before the command is launched.
     -+The first occurrence of substring `$ARG` will be replaced with the
     -+<value> part of an existing trailer with the same <token>, if any,
     -+before the command is launched.
     ++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.
       +
     - If some '<token>=<value>' arguments are also passed on the command
     +-If some '<token>=<value>' arguments are also passed on the command
      -line, when a 'trailer.<token>.command' is configured, the command will
      -also be executed for each of these arguments. And the <value> part of
      -these arguments, if any, will be used to replace the `$ARG` string in
      -the command.
     -+line, when a 'trailer.<token>.command' is configured, the command is run
     -+once for each these arguments with the same <token>. And the <value>
     -+part of these arguments, if any, will be used to replace the first `$ARG`
     -+string in the command.
     ++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>.
       
       EXAMPLES
       --------
 2:  3dc8983a4702 ! 2:  7f645ec95f48 [GSOC] trailer: add new .cmd config option
     @@ Commit message
      
          The `trailer.<token>.command` configuration variable
          specifies a command (run via the shell, so it does not have
     -    to be a single name of or path to the command, but can be a
     +    to be a single name or path to the command, but can be a
          shell script), and the first occurrence of substring $ARG is
          replaced with the value given to the `interpret-trailer`
     -    command for the token.  This has two downsides:
     +    command for the token in a '--trailer <token>=<value>' argument.
     +
     +    This has two downsides:
      
          * The use of $ARG in the mechanism misleads the users that
          the value is passed in the shell variable, and tempt them
     @@ Commit message
          Signed-off-by: ZheNing Hu <adlternative@gmail.com>
      
       ## Documentation/git-interpret-trailers.txt ##
     -@@ Documentation/git-interpret-trailers.txt: trailer.<token>.command::
     - 	be called to automatically add or modify a trailer with the
     - 	specified <token>.
     - +
     --When this option is specified, 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 specified command with any leading and trailing
     --whitespace trimmed off.
     -+When this option is specified, the first occurrence of substring $ARG is
     -+replaced with the value given to the `interpret-trailer` command for the
     -+same token. It passes the value through `$ARG`, otherwise this option behaves
     -+in the same way as 'trailer.<token>.cmd'.
     +@@ Documentation/git-interpret-trailers.txt: trailer.<token>.ifmissing::
     + 	that option for trailers with the specified <token>.
     + 
     + trailer.<token>.command::
     ++	This option behaves in the same way as 'trailer.<token>.cmd', except
     ++	that it doesn't pass anything as argument to the specified command.
     ++	Instead the first occurrence of substring $ARG is replaced by the
     ++	value that would be passed as argument.
     +++
     ++The 'trailer.<token>.command' option has been deprecated in favor of
     ++'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
     ++only replaced once and that the original way of replacing $ARG is not safe.
      ++
     -+The 'trailer.<token>.command' option has been deprecated due to the fact
     -+that $ARG in the user's command can only be replaced once and that the
     -+original way of replacing $ARG was not safe. Now the preferred option is
     -+'trailer.<token>.cmd', which uses a positional argument to pass the value.
     - +
     --The first occurrence of substring `$ARG` will be replaced with the
     --<value> part of an existing trailer with the same <token>, if any,
     --before the command is launched.
      +When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
      +for the same <token>, 'trailer.<token>.cmd' is used and
      +'trailer.<token>.command' is ignored.
      +
      +trailer.<token>.cmd::
     -+	The command specified by this configuration variable is run
     -+	with a single argument, which is the <value> part of a
     -+	`--trailer <token>=<value>` on the command line. The output
     -+	from the command is then used as the value for the <token>
     -+	in the resulting trailer.
     -++
     -+When this option is specified, the behavior is as if a
     -+'--trailer <token>=<value>' argument was added at the beginning of
     -+the "git interpret-trailers" command, the command specified by this
     -+configuration variable will be called with an empty string as the
     -+argument.
     + 	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
     +@@ Documentation/git-interpret-trailers.txt: 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.
     ++of these arguments, if any, will be passed to the command as its
     ++first argument. This way the command can produce a <value> computed
     ++from the <value> passed in the '--trailer <token>=<value>' argument.
       +
     --If some '<token>=<value>' arguments are also passed on the command
     --line, when a 'trailer.<token>.command' is configured, the command is run
     --once for each these arguments with the same <token>. And the <value>
     --part of these arguments, if any, will be used to replace the first `$ARG`
     --string in the command.
     -+If some '--trailer <token>=<value>' arguments are also passed on the
     -+command line, when a 'trailer.<token>.cmd' is configured, the command
     -+is run once for each `--trailer <token>=<value>` on the command line
     -+with the same <token>. And the <value> part of these arguments, if any,
     -+will be passed to the command as its first argument.
     +-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>.
     ++For consistency, the $1 is also passed, this time with the empty string,
     ++in the command when the command is first called to add a trailer with
     ++the specified <token>.
       
       EXAMPLES
       --------