Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 11, 2026, 02:41 UTC
- Message-ID
- <xmqq1pfivfa3.fsf@gitster.g>
- In-Reply-To
- <55d5d53a-ec30-4b72-9ff4-c5a0631620ec@app.fastmail.com>
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 7 quoted lines
> On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail.com wrote: >> From: Kristoffer Haugsbakk <code@khaugsbakk.name> >>[snip] > > Sorry to Ben here who I forgot to set on copy. :/ > > +Cc now.
It has been quite a while and I have no recollection if there were still necessary adjustments or not. Is everybody happy with the final text?
https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/
Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc index 77b4f63b05..b42f957d66 100644 --- a/Documentation/git-interpret-trailers.adoc +++ b/Documentation/git-interpret-trailers.adoc @@ -3,7 +3,7 @@ git-interpret-trailers(1) NAME ---- -git-interpret-trailers - Add or parse structured information in commit messages +git-interpret-trailers - Add or parse metadata in commit messages SYNOPSIS -------- @@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines that look similar to RFC 822 e-mail -headers, at the end of the otherwise free-form part of a commit -message. For example, in the following commit message +Add or parse trailers metadata at the end of the otherwise +free-form part of a commit message, or any other kind of text. + +A _trailer_ in its simplest form is a key-value pair with a colon as a +separator. The _key_ consists of ASCII alphanumeric characters and +hyphens (`-`). A _trailer block_ consists of one or more trailers. The +trailer block needs to be preceded by a blank line, where a _blank line_ +is either an empty or a whitespace-only line. For example, in the +following commit message ------------------------------------------------ subject @@ -81,19 +87,25 @@ trailer.sign.key "Signed-off-by: " in your configuration, you only need to specify `--trailer="sign: foo"` on the command line instead of `--trailer="Signed-off-by: foo"`. -By default the new trailer will appear at the end of all the existing -trailers. If there is no existing trailer, the new trailer will appear -at the end of the input. A blank line will be added before the new -trailer if there isn't one already. +By default the new trailer will appear at the end of the trailer block. +A trailer block will be created with only that trailer if a trailer +block does not already exist. Recall that a trailer block needs to be +preceded by a blank line, so a blank line (specifically an empty line) +will be inserted before the new trailer block in that case. -Existing trailers are extracted from the input by looking for -a group of one or more lines that (i) is all trailers, or (ii) contains at -least one Git-generated or user-configured trailer and consists of at +Existing trailers are extracted from the input by looking for the +trailer block. Concretely, that is a group of one or more lines that (i) +is all trailers, or (ii) contains at least one Git-generated or +user-configured trailer and consists of at least 25% trailers. -The group must be preceded by one or more empty (or whitespace-only) lines. -The group must either be at the end of the input or be the last -non-whitespace lines before a line that starts with `---` (followed by a -space or the end of the line). +The trailer block is by definition at the end the the message. The end +of the message in turn is either (i) at the end of the input, or (ii) +the last non-whitespace lines before a line that starts with `---` +(followed by a space or the end of the line). + +This command ignores comment lines (see `core.commentString` in +linkgit:git-config[1]). This is for use with the `prepare-commit-msg` +and `commit-msg` hooks. When reading trailers, there can be no whitespace before or inside the _<key>_, but any number of regular space and tab characters are allowed @@ -107,9 +119,6 @@ key: This is a very long value, with spaces and newlines in it. ------------------------------------------------ -Note that trailers do not follow (nor are they intended to follow) many of the -rules for RFC 822 headers. For example they do not follow the encoding rule. - OPTIONS ------- `--in-place`:: @@ -402,6 +411,29 @@ mv "\$1.new" "\$1" $ chmod +x .git/hooks/commit-msg ------------ +* Here we try to to use three different trailer keys. But it fails + because two of them are not recognized as trailer keys. ++ +---- +$ cat msg.txt +subject + +Skapad-på: some-branch +Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c +Reviewed-by: Alice <alice@example.com> +$ git interpret-trailers --only-trailers <msg.txt +$ +---- ++ +Recall that a trailer key has to consist of only ASCII alphanumeric +characters and hyphens, and this does not hold for the two first +supposed trailer keys. And now none are recognized as trailers because +the candidate trailer block has at least one non-trailer line, even +though `Reviewed-by` is a valid trailer key. Recall that a trailer block +has to either (i) be all trailers, or (ii) consist of at least one +Git-generated or user-configured trailer (and some other conditions). +And (ii) is not satisfied since we have not configured any trailer keys. + SEE ALSO -------- linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]