git/Documentation/git-interpret-trailers.txt, branch v2.33.6

trailer: add new .cmd config option

2021-05-04T03:09:43Z

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

docs: correct descript of trailer..command

2021-05-04T03:09:43Z

In the original documentation of `trailer..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 Signed-off-by: Junio C Hamano

interpret-trailers.txt: start the desc line with a capital letter

2019-04-01T06:49:47Z

This description line is shown in 'git help -a' and all other commands description starts with an uppercase character. This just makes that printout a bit nicer. Signed-off-by: Nguyễn Thái Ngọc Duy Signed-off-by: Junio C Hamano

Merge branch 'jk/trailer-fixes'

2018-09-17T20:53:54Z

"git interpret-trailers" and its underlying machinery had a buggy code that attempted to ignore patch text after commit log message, which triggered in various codepaths that will always get the log message alone and never get such an input. * jk/trailer-fixes: append_signoff: use size_t for string offsets sequencer: ignore "---" divider when parsing trailers pretty, ref-filter: format %(trailers) with no_divider option interpret-trailers: allow suppressing "---" divider interpret-trailers: tighten check for "---" patch boundary trailer: pass process_trailer_opts to trailer_info_get() trailer: use size_t for iterating trailer list trailer: use size_t for string offsets

interpret-trailers: allow suppressing "---" divider

2018-08-23T17:08:51Z

Even with the newly-tightened "---" parser, it's still possible for a commit message to trigger a false positive if it contains something like "--- foo". If the caller knows that it has only a single commit message, it can now tell us with the "--no-divider" option, eliminating any false positives. If we were designing this from scratch, I'd probably make this the default. But we've advertised the "---" behavior in the documentation since interpret-trailers has existed. Since it's meant to be scripted, breaking that would be a bad idea. Note that the logic is in the underlying trailer.c code, which is used elsewhere. The default there will keep the current behavior, but many callers will benefit from setting this new option. That's left for future patches. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

interpret-trailers: tighten check for "---" patch boundary

2018-08-23T17:08:51Z

The interpret-trailers command accepts not only raw commit messages, but it also can manipulate trailers in format-patch output. That means it must find the "---" boundary separating the commit message from the patch. However, it does so by looking for any line starting with "---", regardless of whether there is further content. This is overly lax compared to the parsing done in mailinfo.c's patchbreak(), and may cause false positives (e.g., t/perf output tables uses dashes; if you cut and paste them into your commit message, it fools the parser). We could try to reuse patchbreak() here, but it actually has several heuristics that are not of interest to us (e.g., matching "diff -" without a three-dash separator or even a CVS "Index:" line). We're not interested in taking in whatever random cruft people may send, but rather handling git-formatted patches. Note that the existing documentation was written in a loose way, so technically we are changing the behavior from what it said. But this should implement the original intent in a more accurate way. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'sb/trailers-docfix'

2018-08-15T22:08:19Z

Doc update. * sb/trailers-docfix: Documentation/git-interpret-trailers: explain possible values

Documentation/git-interpret-trailers: explain possible values

2018-07-20T22:23:59Z

Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano

Use proper syntax for replaceables in command docs

2018-05-25T08:16:47Z

The standard for command documentation synopses appears to be: [...] means optional <...> means replaceable [<...>] means both optional and replaceable So fix a number of doc pages that use incorrect variations of the above. Signed-off-by: Robert P. J. Day Signed-off-by: Junio C Hamano

Merge branch 'bc/doc-interpret-trailers-grammofix'

2018-02-27T18:34:00Z

Docfix. * bc/doc-interpret-trailers-grammofix: docs/interpret-trailers: fix agreement error