From c364b7ef51ec3af871754e7afdfd73e4bed6da56 Mon Sep 17 00:00:00 2001 From: ZheNing Hu Date: Mon, 3 May 2021 15:41:05 +0000 Subject: trailer: add new .cmd config option The `trailer..command` configuration variable specifies a command (run via the shell, so it does not have 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 in a '--trailer =' argument. This has three downsides: * The use of $ARG in the mechanism misleads the users that the value is passed in the shell variable, and tempt them to use $ARG more than once, but that would not work, as the second and subsequent $ARG are not replaced. * Because $ARG is textually replaced without regard to the shell language syntax, even '$ARG' (inside a single-quote pair), which a user would expect to stay intact, would be replaced, and worse, if the value had an unmatched single quote (imagine a name like "O'Connor", substituted into NAME='$ARG' to make it NAME='O'Connor'), it would result in a broken command that is not syntactically correct (or worse). * The first occurrence of substring `$ARG` will be replaced with the empty string, in the command when the command is first called to add a trailer with the specified . This is a bad design, the nature of automatic execution causes it to add a trailer that we don't expect. Introduce a new `trailer..cmd` configuration that takes higher precedence to deprecate and eventually remove `trailer..command`, which passes the value as an argument to the command. Instead of "$ARG", users can refer to the value as positional argument, $1, in their scripts. At the same time, in order to allow `git interpret-trailers` to better simulate the behavior of `git command -s`, 'trailer..cmd' will not automatically execute. Helped-by: Junio C Hamano Helped-by: Christian Couder Signed-off-by: ZheNing Hu Signed-off-by: Junio C Hamano --- Documentation/git-interpret-trailers.txt | 75 ++++++++++++++++++++++++++++---- 1 file changed, 66 insertions(+), 9 deletions(-) (limited to 'Documentation/git-interpret-trailers.txt') diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 6f2a7a1304..956a01d184 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -232,6 +232,20 @@ trailer..ifmissing:: that option for trailers with the specified . trailer..command:: + This option behaves in the same way as 'trailer..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..command' option has been deprecated in favor of +'trailer..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. ++ +When both 'trailer..cmd' and 'trailer..command' are given +for the same , 'trailer..cmd' is used and +'trailer..command' is ignored. + +trailer..cmd:: This option can be used to specify a shell command that will be called: once to automatically add a trailer with the specified , and then each time a '--trailer =' argument to modify the of @@ -247,15 +261,9 @@ leading and trailing whitespace trimmed off. If some '--trailer =' arguments are also passed on the command line, the command is called again once for each of these arguments with the same . And the 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 computed from the passed -in the '--trailer =' 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 . +of these arguments, if any, will be passed to the command as its +first argument. This way the command can produce a computed +from the passed in the '--trailer =' argument. EXAMPLES -------- @@ -338,6 +346,55 @@ subject Fix #42 ------------ +* Configure a 'help' trailer with a cmd use a script `glog-find-author` + which search specified author identity from git log in git repository + and show how it works: ++ +------------ +$ cat ~/bin/glog-find-author +#!/bin/sh +test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true +$ git config trailer.help.key "Helped-by: " +$ git config trailer.help.ifExists "addIfDifferentNeighbor" +$ git config trailer.help.cmd "~/bin/glog-find-author" +$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" < subject +> +> message +> +> EOF +subject + +message + +Helped-by: Junio C Hamano +Helped-by: Christian Couder +------------ + +* Configure a 'ref' trailer with a cmd use a script `glog-grep` + to grep last relevant commit from git log in the git repository + and show how it works: ++ +------------ +$ cat ~/bin/glog-grep +#!/bin/sh +test -n "$1" && git log --grep "$1" --pretty=reference -1 || true +$ git config trailer.ref.key "Reference-to: " +$ git config trailer.ref.ifExists "replace" +$ git config trailer.ref.cmd "~/bin/glog-grep" +$ git interpret-trailers --trailer="ref:Add copyright notices." < subject +> +> message +> +> EOF +subject + +message + +Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) +------------ + * Configure a 'see' trailer with a command to show the subject of a commit that is related, and show how it works: + -- cgit v1.3