summaryrefslogtreecommitdiff
path: root/Documentation/git-interpret-trailers.txt
AgeCommit message (Collapse)AuthorFilesLines
2021-05-04trailer: add new .cmd config optionLibravatar ZheNing Hu1-9/+66
The `trailer.<token>.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 <token>=<value>' 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 <token>. 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.<token>.cmd` configuration that takes higher precedence to deprecate and eventually remove `trailer.<token>.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.<token>.cmd' will not automatically execute. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Christian Couder <christian.couder@gmail.com> Signed-off-by: ZheNing Hu <adlternative@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-05-04docs: correct descript of trailer.<token>.commandLibravatar ZheNing Hu1-16/+21
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>
2019-04-01interpret-trailers.txt: start the desc line with a capital letterLibravatar Nguyễn Thái Ngọc Duy1-1/+1
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 <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-09-17Merge branch 'jk/trailer-fixes'Libravatar Junio C Hamano1-2/+8
"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
2018-08-23interpret-trailers: allow suppressing "---" dividerLibravatar Jeff King1-1/+6
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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-23interpret-trailers: tighten check for "---" patch boundaryLibravatar Jeff King1-2/+3
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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-15Merge branch 'sb/trailers-docfix'Libravatar Junio C Hamano1-3/+6
Doc update. * sb/trailers-docfix: Documentation/git-interpret-trailers: explain possible values
2018-07-20Documentation/git-interpret-trailers: explain possible valuesLibravatar Stefan Beller1-3/+6
Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-25Use proper syntax for replaceables in command docsLibravatar Robert P. J. Day1-2/+2
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 <rpjday@crashcourse.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-02-27Merge branch 'bc/doc-interpret-trailers-grammofix'Libravatar Junio C Hamano1-1/+1
Docfix. * bc/doc-interpret-trailers-grammofix: docs/interpret-trailers: fix agreement error
2018-02-13docs/interpret-trailers: fix agreement errorLibravatar brian m. carlson1-1/+1
In the description of git interpret-trailers, we describe "a group…of lines" that have certain characteristics. Ensure both options describing this group use a singular verb for parallelism. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-26Merge branch 'jk/trailers-parse'Libravatar Junio C Hamano1-7/+26
"git interpret-trailers" has been taught a "--parse" and a few other options to make it easier for scripts to grab existing trailer lines from a commit log message. * jk/trailers-parse: doc/interpret-trailers: fix "the this" typo pretty: support normalization options for %(trailers) t4205: refactor %(trailers) tests pretty: move trailer formatting to trailer.c interpret-trailers: add --parse convenience option interpret-trailers: add an option to unfold values interpret-trailers: add an option to show only existing trailers interpret-trailers: add an option to show only the trailers trailer: put process_trailers() options into a struct
2017-08-20doc/interpret-trailers: fix "the this" typoLibravatar Martin Ågren1-1/+1
Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-15interpret-trailers: add --parse convenience optionLibravatar Jeff King1-7/+14
The last few commits have added command line options that can turn interpret-trailers into a parsing tool. Since they'd most often be used together, let's provide a convenient single option for callers to invoke this mode. This is implemented as a callback rather than a boolean so that its effect is applied immediately, as if those options had been specified. Later options can then override them. E.g.: git interpret-trailers --parse --no-unfold would work. Let's also update the documentation to make clear that this parsing mode behaves quite differently than the normal "add trailers to the input" mode. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-15interpret-trailers: add an option to unfold valuesLibravatar Jeff King1-0/+4
The point of "--only-trailers" is to give a caller an output that's easy for them to parse. Getting rid of the non-trailer material helps, but we still may see more complicated syntax like whitespace continuation. Let's add an option to unfold any continuation, giving the output as a single "key: value" line per trailer. As a bonus, this could be used even without --only-trailers to clean up unusual formatting in the incoming data. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-15interpret-trailers: add an option to show only existing trailersLibravatar Jeff King1-0/+5
It can be useful to invoke interpret-trailers for the primary purpose of parsing existing trailers. But in that case, we don't want to apply existing ifMissing or ifExists rules from the config. Let's add a special mode where we avoid applying those rules. Coupled with --only-trailers, this gives us a reasonable parsing tool. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-15interpret-trailers: add an option to show only the trailersLibravatar Jeff King1-0/+3
In theory it's easy for any reader who wants to parse trailers to do so. But there are a lot of subtle corner cases around what counts as a trailer, when the trailer block begins and ends, etc. Since interpret-trailers already has our parsing logic, let's let callers ask it to just output the trailers. They still have to parse the "key: value" lines, but at least they can ignore all of the other corner cases. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-14interpret-trailers: fix documentation typoLibravatar Paolo Bonzini1-2/+2
Self-explanatory... trailer.ifexists is documented with the right name, but after a while it switches to ifexist. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-14interpret-trailers: add options for actionsLibravatar Paolo Bonzini1-0/+23
Allow using non-default values for trailers without having to set them up in .gitconfig first. For example, if you have the following configuration trailer.signed-off-by.where = end you may use "--where before" when a patch author forgets his Signed-off-by and provides it in a separate email. Likewise for --if-exists and --if-missing Reverting to the behavior specified by .gitconfig is done with --no-where, --no-if-exists and --no-if-missing. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-05-23Documentation: fix reference to ifExists for interpret-trailersLibravatar Andreas Heiduk1-1/+1
The manual for "git interpret-trailers" mentioned a non-existing literal `overwrite` for its config option `trailer.ifexists`. The correct name for that choice is `replace`. Signed-off-by: Andreas Heiduk <asheiduk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-11-21doc: mention user-configured trailersLibravatar Jonathan Tan1-1/+2
In commit 1462450 ("trailer: allow non-trailers in trailer block", 2016-10-21), functionality was added (and tested [1]) to allow non-trailer lines in trailer blocks, as long as those blocks contain at least one Git-generated or user-configured trailer, and consists of at least 25% trailers. The documentation was updated to mention this new functionality, but did not mention "user-configured trailer". Further update the documentation to also mention "user-configured trailer". [1] "with non-trailer lines mixed with a configured trailer" in t/t7513-interpret-trailers.sh Signed-off-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-21trailer: support values folded to multiple linesLibravatar Jonathan Tan1-3/+4
Currently, interpret-trailers requires that a trailer be only on 1 line. For example: a: first line second line would be interpreted as one trailer line followed by one non-trailer line. Make interpret-trailers support RFC 822-style folding, treating those lines as one logical trailer. Signed-off-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-21trailer: forbid leading whitespace in trailersLibravatar Jonathan Tan1-1/+1
Currently, interpret-trailers allows leading whitespace in trailer lines. This leads to false positives, especially for quoted lines or bullet lists. Forbid leading whitespace in trailers. Signed-off-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-21trailer: allow non-trailers in trailer blockLibravatar Jonathan Tan1-2/+3
Currently, interpret-trailers requires all lines of a trailer block to be trailers (or comments) - if not it would not identify that block as a trailer block, and thus create its own trailer block, inserting a blank line. For example: echo -e "\nSigned-off-by: x\nnot trailer" | git interpret-trailers --trailer "c: d" would result in: Signed-off-by: x not trailer c: d Relax the definition of a trailer block to require that the trailers (i) are all trailers, or (ii) contain at least one Git-generated trailer and consists of at least 25% trailers. Signed-off-by: x not trailer c: d (i) is the existing functionality. (ii) allows arbitrary lines to be included in trailer blocks, like those in [1], and still allow interpret-trailers to be used. [1] https://kernel.googlesource.com/pub/scm/linux/kernel/git/stable/linux-stable/+/e7d316a02f683864a12389f8808570e37fb90aa3 Signed-off-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-28doc: typeset long command-line options as literalLibravatar Matthieu Moy1-1/+1
Similarly to the previous commit, use backquotes instead of forward-quotes, for long options. This was obtained with: perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt and manual tweak to remove false positive in ascii-art (o'--o'--o' to describe rewritten history). Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-14interpret-trailers: add option for in-place editingLibravatar Tobias Klauser1-1/+23
Add a command line option --in-place to support in-place editing akin to sed -i. This allows to write commands like the following: git interpret-trailers --trailer "X: Y" a.txt > b.txt && mv b.txt a.txt in a more concise way: git interpret-trailers --trailer "X: Y" --in-place a.txt Signed-off-by: Tobias Klauser <tklauser@distanz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-10-15Merge branch 'tk/doc-interpret-trailers-grammo'Libravatar Junio C Hamano1-1/+1
* tk/doc-interpret-trailers-grammo: Documentation/interpret-trailers: Grammar fix
2015-10-07Documentation/interpret-trailers: Grammar fixLibravatar Tobias Klauser1-1/+1
Signed-off-by: Tobias Klauser <tklauser@distanz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-11-04Documentation: typofixesLibravatar Thomas Ackermann1-3/+3
In addition to fixing trivial and obvious typos, be careful about the following points: - Spell ASCII, URL and CRC in ALL CAPS; - Spell Linux as Capitalized; - Do not omit periods in "i.e." and "e.g.". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-10-13Documentation: add documentation for 'git interpret-trailers'Libravatar Christian Couder1-0/+314
While at it add git-interpret-trailers to "command-list.txt". Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>