git-interpret-trailers and period characters in the key
Hi folks,
Just debugging one of my scripts and I found that git-interpret-trailers behaves surprisingly on trailer keys containing '.' characters:
❯❯ cat commit.txt
my commit title
My-Footer: foo
❯❯ git interpret-trailers --parse commit.txt
My-Footer: foo
❯❯ cat commit2.txt
my commit title
My-Footer: foo
My-6.11-Version: bar
❯❯ git interpret-trailers --parse commit.txt
Basically, as soon as any trailer key contains a period (which in my case, it does because the trailer keys refer to versions of of software, i.e. "this commit was backported from the following Linux kernel commit which appeared in version 6.1"), it stops parsing the trailer block.
My guess is that this is just that it doesn't allow periods in the trailer key, and once there's one line in the block that isn't a trailer, it no longer meets the requirements described in the man page.
I can't find anything in the man page about why the period character should break this. Am I missing anything there?
Cheers,
Brendan
❯❯ git --version
git version 2.49.0.472.ge94155a9ec-goog
(IIUC that -goog in the version string is just noting that we have monitoring logic added to our internal Git built to spot people leaking IP, there's no actual feature customisation)
Hi,
Quoted 10 lines · Brendan Jackman
Basically, as soon as any trailer key contains a period (which in my case, it does because the trailer keys refer to versions of of software, i.e. "this commit was backported from the following Linux kernel commit which appeared in version 6.1"), it stops parsing the trailer block.
My guess is that this is just that it doesn't allow periods in the trailer key, and once there's one line in the block that isn't a trailer, it no longer meets the requirements described in the man page.
Yeah, it's also my guess that the trailer block is not considered a trailer block anymore as your trailer key is not considered a valid trailer key.
Quoted 2 lines
I can't find anything in the man page about why the period character should break this. Am I missing anything there?
We tried to be quite strict when implementing trailers to avoid regular text to be too easily considered trailers.
Having a config option or something to be a bit more lenient and accept more characters in trailer keys could help some people, and it might not be very difficult to implement. On the other hand if people start to have a lot of weird trailers around, and abuse the config option to make it too lenient, then it could be a bad thing in general as more and more regular text might be interpreted as trailers.
I also agree that our doc about this could be improved. Patches welcome.
Best,
Christian.
Quoted 8 lines · Christian Couder
Having a config option or something to be a bit more lenient and accept more characters in trailer keys could help some people, and it might not be very difficult to implement. On the other hand if people start to have a lot of weird trailers around, and abuse the config option to make it too lenient, then it could be a bad thing in general as more and more regular text might be interpreted as trailers.
I also agree that our doc about this could be improved. Patches welcome.
Thanks for a concise summary.
I agree that loosening the rule, or even adding an option to loosen the rule, is detrimental to the ecosystem at large, and documentation can be improved.
In retrospect, I supsect that it even was a mistake to special case the #BUGID syntax when the trailer was pretty much about lines that look similar to E-Mail-Header: fields. Let's not make it worse.
Thanks.
cover doc: interpret-trailers: explain key format
In reply to Brendan JackmanFrom: Kristoffer Haugsbakk <[email protected]>
Topic name: doc-int-tr-2-key-format
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors.
To facilitate this there is a first commit/patch to reorient the introduction towards discussing “key-value pairs”, since that makes it easier to follow up with an explanation of the *key* format.
§ Cc
Linus Arver as the author of the example that this change touches.
[1/2] doc: interpret-trailers: stop fixating on RFC 822 [2/2] doc: interpret-trailers: explain key format
Documentation/git-interpret-trailers.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)
base-commit: 5361983c075154725be47b65cca9a2421789e410
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH 1/2 doc: interpret-trailers: stop fixating on RFC 822
From: Kristoffer Haugsbakk <[email protected]>
This command handles the *trailers* key–value pair format. But the command isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers.
This is overwrought:
• most people do not deal directly with email headers or think about email RFCs; and
• simply calling them “key-value pairs” should be more than suggestive enough considering the context here.
Se let’s call the format just that, show the example, and then briefly explain the format of the keys (coming up); this change facilitates the next commit where we will explain what characters are permitted in the key.
Concretely, let’s replace the introduction with “key-value pairs” and remove the last mention of RFC 822, but keep the innocuous comparison with email line folding in the middle. We do not need the final disclaimer now that the *only* mention of email headers is that Git trailers have something similar to email line folding; there is no invitation to speculate that trailers would follow any other email format rules since we do not compare them directly any more.
❦
Talking about trailers as an RFC 822/2822-like format seems to go back to the --fixes/Fixes: trailer topic,[1] the thread that precipitated this command and in turn the first trailer support in git(1) beyond adding s-o-b lines.
† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/
---
Notes (series):
The (❦) is meant as a thematic break. There is too much of a thematic jump between these two paragraphs without a section or something else breaking them up.
(one was not tempted to use --- here)
Documentation/git-interpret-trailers.adoc | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +3 -6
@@ -14,9 +14,9 @@ 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 _trailer_ key-value pairs at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject
@@ -107,9 +107,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`::
Signature · 1 line
2.53.0.32.gf6228eaf9cc
Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822
Quoted 4 lines · [email protected] writes:
Notes (series):
The (❦) is meant as a thematic break. There is too much of a thematic jump between these two paragraphs without a section or something else breaking them up.
I do not quite agree with this particular instance. It rather looks more like an unnecessary hostile move against folks who prefer to see plain ASCII on their screen unless absolutely needed (like say for displaying people's names with letters outside US-ASCII), as the two paragraphs before and after are not all that unrelated.
One thing that I found a bit wanting after this step is that it lost hint that the primary way to delimit between the key and value in the trailer lines is to have a colon immediately after key and with a single whitespace before the value, which is what is very typical to see in the e-mail headers. Sure, if a reader has not heard of (2)822, hinting that these resemble e-mail headers would not help them at all, but those of us among the audience of this document who have seen e-mail headers and how they feel, the "look similar to" was enough to hint how a colon is typically used in a trailer. In the updated text, the readers will have to way around line #65 before seeing the official "both key and value are trimmed for whitespaces on both ends and then made into 'key: value'".
I mentioned "issues I raised on the previous step" in my review on 2/2, but did not remember that I haven't sent out this one yet ;-)
Quoted 13 lines
Documentation/git-interpret-trailers.adoc +3
-3@@ -14,9 +14,9 @@ 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 _trailer_ key-value pairs at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject
Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822
Quoted 11 lines · Junio C Hamano
Quoted 4 lines · [email protected] writes:
Notes (series):
The (❦) is meant as a thematic break. There is too much of a thematic jump between these two paragraphs without a section or something else breaking them up.I do not quite agree with this particular instance. It rather looks more like an unnecessary hostile move against folks who prefer to see plain ASCII on their screen unless absolutely needed (like say for displaying people's names with letters outside US-ASCII)
We can use *** instead.
Quoted 1 line
, as the two paragraphs before and after are not all that unrelated.
Or nothing.
Quoted 13 lines
One thing that I found a bit wanting after this step is that it lost hint that the primary way to delimit between the key and value in the trailer lines is to have a colon immediately after key and with a single whitespace before the value, which is what is very typical to see in the e-mail headers. Sure, if a reader has not heard of (2)822, hinting that these resemble e-mail headers would not help them at all, but those of us among the audience of this document who have seen e-mail headers and how they feel, the "look similar to" was enough to hint how a colon is typically used in a trailer. In the updated text, the readers will have to way around line #65 before seeing the official "both key and value are trimmed for whitespaces on both ends and then made into 'key: value'".
Quoted 2 lines
I mentioned "issues I raised on the previous step" in my review on 2/2, but did not remember that I haven't sent out this one yet ;-)
Okay. See my previous email about adding the “separated by” part.
I only mentioned the colon there (prev. email). Not the space. The reason is the same as what I wrote in the commit message. We say that these are key–value pairs and only use :SP in all the examples. I think just pointing out the colon at the start is enough detail at that point before all the details reveal themselves near the end of the Description section.
IMO it’s best to stick to the normalized :SP when writing as well, even though you can write : without any whitespace. But I can’t imagine readers being motivated to try to deviate from the normalized separator form; the doc just uses :SP... so why not just use that as well? Compare with the key format: people *will* (or have) tried with dots/periods, maybe also Unicode like
Skapad-på: feature-branch-something
... because that has some data content (not just syntactic variation as is the case for the separator format).
Quoted 1 line
[snip]
Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822
Quoted 1 line · Kristoffer Haugsbakk
IMO it’s best to stick to the normalized
:SP when writing as well,
Absolutely. That is why I suggested to mention colon somewhere when we talk about key and value. Your 2/2 with minor fixes you alluded to in your review response made the worry I raised for 1/2 go away.
Thanks.
PATCH 2/2 doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and painting their trailers by numbers (by the documentation examples).
The previous commit for “key–value pairs” allows us to segue right into describing these lines as consisting of a key and a value, which is our opening to describing the key format.
Just like *trailer* we emphasize these two first standalone word mentions. They are then mostly used in placeholders throughout the rest of the document (<key> and <value>).
---
Notes (series):
trailer.c uses isalnum(). That short research together with a little testing left me with this conclusion. (The C unit tests for trailers and t7513-interpret-trailers.sh seem to just use lines with spaces and no separators for non-trailer lines.)
Documentation/git-interpret-trailers.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +4 -1
@@ -27,7 +27,10 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------ -the last two lines starting with `Signed-off-by` are trailers. +the last two lines starting with `Signed-off-by` are trailers. These two +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob). +The key must consist of only ASCII alphanumeric characters and hyphens +(`-`). The hyphens serve as interword separators. This command reads commit messages from either the _<file>_ arguments or the standard input if no _<file>_ is specified.
Signature · 1 line
2.53.0.32.gf6228eaf9cc
Re: [PATCH 2/2] doc: interpret-trailers: explain key format
Quoted 6 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and painting their trailers by numbers (by the documentation examples).
"paint"? I am not sure what the latter half of the above paragraph wants to say, even though I do agree that being explicit about the allowed characters is a good idea.
Quoted 3 lines
The previous commit for “key–value pairs” allows us to segue right into describing these lines as consisting of a key and a value, which is our opening to describing the key format.
And it is a good place to remedy the issue I raised for the previous step as well ;-)
Quoted 2 lines
Just like *trailer* we emphasize these two first standalone word mentions.
Again, I have no idea what "these two first standalone word" wants to refer to. It is not even clear to me if it refers to a single thing, or two things---the verb "mentions" hints that the subject of the sentence must be plural, but I cannot tell what two things you are referring to.
Documentation/git-interpret-trailers.adoc Signed-off-by: Alice <[email protected]> · line 31
Quoted 11 lines
Documentation/git-interpret-trailers.adoc +2
-1@@ -27,7 +27,10 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------ -the last two lines starting with `Signed-off-by` are trailers. +the last two lines starting with `Signed-off-by` are trailers. These two +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).
Remedy the loss of "e-mail like" by ending the above sentence more like:
... and Bob), with a colon appended at the end of the key.
Documentation/git-interpret-trailers.adoc Signed-off-by: Alice <[email protected]> · line 33
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+The key must consist of only ASCII alphanumeric characters and hyphens +(`-`). The hyphens serve as interword separators.
The first sentence is a very much welcome addition. I however doubt that the last sentence is necessary or beneficial, as "SignedOffBy" is a perfectly fine key to be used for a trailer if a project prefers (not this project, though). I would not object to
The hyphens can be used as inter-word separators.
or
The hyphens can be used as inter-word separators, if you want.
but any expression that can be misinterpreted that the document strongly suggests projects and communities to adopt the "hyphen as inter-word separator" convention is not very welcome.
Thanks.
Re: [PATCH 2/2] doc: interpret-trailers: explain key format
Quoted 4 lines · Junio C Hamano
Quoted 2 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Quoted 8 lines
Quoted 4 lines
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and painting their trailers by numbers (by the documentation examples).
"paint"? I am not sure what the latter half of the above paragraph wants to say, even though I do agree that being explicit about the allowed characters is a good idea.
“Paint by numbers”, “paint inside the lines.” Using the docs as a guide to create very similar-looking keys. Contrast with the original issue here:
Basically, as soon as any trailer key contains a period (which in my case, it does because the trailer keys refer to versions of of software, i.e. "this commit was backported from the following Linux kernel commit which appeared in version 6.1"), [...]
A symptom of taking the examples from the doc and adding just a little extra to it.
This cutesy phrasing can be dropped. We’ll see.
Quoted 7 lines
Quoted 3 lines
The previous commit for “key–value pairs” allows us to segue right into describing these lines as consisting of a key and a value, which is our opening to describing the key format.
And it is a good place to remedy the issue I raised for the previous step as well ;-)
Quoted 8 lines
Quoted 2 lines
Just like *trailer* we emphasize these two first standalone word mentions.
Again, I have no idea what "these two first standalone word" wants to refer to. It is not even clear to me if it refers to a single thing, or two things---the verb "mentions" hints that the subject of the sentence must be plural, but I cannot tell what two things you are referring to.
Key & value.
Something like:
Just like *trailer* we emphasize these two first standalone word mentions (key and value).
They are the only emphasized words in the diff. Although I *have* relied too much on the diff context before.
Quoted 9 lines
Quoted 9 lines
Documentation/git-interpret-trailers.adoc +0
-0@@ -27,7 +27,10 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------
Quoted 7 lines
Documentation/git-interpret-trailers.adoc Signed-off-by: Alice <[email protected]> · line 31
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +2
-1-the last two lines starting with `Signed-off-by` are trailers. +the last two lines starting with `Signed-off-by` are trailers. These two +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).Remedy the loss of "e-mail like" by ending the above sentence more like:
... and Bob), with a colon appended at the end of the key.
Okay. I’ll try with:
... and Bob), with a colon separating the key and the value.
Quoted 11 lines
Documentation/git-interpret-trailers.adoc Signed-off-by: Alice <[email protected]> · line 33
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +2
-0+The key must consist of only ASCII alphanumeric characters and hyphens +(`-`). The hyphens serve as interword separators.The first sentence is a very much welcome addition. I however doubt that the last sentence is necessary or beneficial, as "SignedOffBy" is a perfectly fine key to be used for a trailer if a project prefers (not this project, though). I would not object to
The hyphens can be used as inter-word separators.
Quoted 7 lines
or
The hyphens can be used as inter-word separators, if you want.
but any expression that can be misinterpreted that the document strongly suggests projects and communities to adopt the "hyphen as inter-word separator" convention is not very welcome.
I’ll take the first one here.
Thank you!
Re: [PATCH 2/2] doc: interpret-trailers: explain key format
Quoted 18 lines · Kristoffer Haugsbakk
Quoted 10 lines · Junio C Hamano
Quoted 2 lines · [email protected] writes:
Just like *trailer* we emphasize these two first standalone word mentions.
Again, I have no idea what "these two first standalone word" wants to refer to. It is not even clear to me if it refers to a single thing, or two things---the verb "mentions" hints that the subject of the sentence must be plural, but I cannot tell what two things you are referring to.
Key & value.
Quoted 7 lines
Something like:
Just like *trailer* we emphasize these two first standalone word mentions (key and value).
They are the only emphasized words in the diff. Although I *have* relied too much on the diff context before.
Perhaps “we emphasize the introduction of the terms ‘key’ and ‘value’” (much like a technical manual or paper may emphasize the first use of a new word or abbreviation, making subsequent uses link to it so readers can find the definition)?
I do find it interesting that the introduction is with an example rather than a definition. This suits “learning order” (concrete->abstract), but not necessarily “reference order” (where I just want to get to the definition). Hm.
I’m not sure I have any concrete suggestions, though.
Re: [PATCH 2/2] doc: interpret-trailers: explain key format
Quoted 10 lines · Ben Knoble
Quoted 10 lines · Kristoffer Haugsbakk
Quoted 1 line
[snip]
Key & value.
Something like:
Just like *trailer* we emphasize these two first standalone word mentions (key and value).
Quoted 7 lines
Quoted 2 lines
They are the only emphasized words in the diff. Although I *have* relied too much on the diff context before.
Perhaps “we emphasize the introduction of the terms ‘key’ and ‘value’” (much like a technical manual or paper may emphasize the first use of a new word or abbreviation, making subsequent uses link to it so readers can find the definition)?
I think I’ll steal that. Thanks!
Quoted 2 lines
I do find it interesting that the introduction is with an example rather than a definition.
The example is from Linus Arver in d57fa7fc (doc: trailer: add more examples in DESCRIPTION, 2023-06-15).[1] The version before that[2] indirectly showed a token: value example (“will appear in the output like”) after five paragraphs.
† 1: One review comment: https://lore.kernel.org/git/[email protected]/
† 2: git show d57fa7fc73202af226b6c0^1:Documentation/git-interpret-trailers.txt
Quoted 4 lines
This suits “learning order” (
concrete->abstract), but not necessarily “reference order” (where I just want to get to the definition). Hm.I’m not sure I have any concrete suggestions, though.
I think the only practical starting point for this format is the simplest case first, namely:
1. One line per trailer (c.f. the value takes up multiple lines)
2. Non-empty values (see --trim-empty)
3. Default separator
4. No non-trailer lines
5. No configuration
Currently that starts off with two examples. But let’s try the other way around:
***
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 such trailers. The trailer block needs to be preceded by a blank line.[**1**] In other words:
<text>
<key>: <value>Where <key> consists of ASCII alphanumeric characters and hyphens. For example:
[we’re back to the original example]
------------------------------------------------
subject
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
------------------------------------------------
***
Also optionally interject some words about commit messages and whatnot (or even tag messages for that matter, now).
I was originally feeling skeptical of changing to something like reference-first. But I like this now that I have gone through the exercise of trying it out. So thanks for mentioning it. ;)
[**1**]: git-commit(1) stripspace behavior etc. doesn’t make this
obvious but you can have just a blank line and then a trailer block. You don’t need any text before the blank line. LF indicates the blank line:
LF
Signed-off-by: Me
v2 cover doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.
To that end, an overview of the changes:
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain the “key” format, and add a new example
• Patch 8: Also use the “trailer block” term introduced to the doc in patch 5 later in the doc
• Patch 9: document line comment behavior
§ Changes in v2
Here one thing lead to another, mostly because changing one part of the doc necessitated knock-on changes. An exception though is the last patch which could be added later/separately.
As for the changes requested after the review on v1:
• Add missing mention of the default separator (:)
• Remove confusing “paint by numbers” reference
• Remove “The hyphens serve as interword separators”. This is a normative statement.
An advisory statement would have been fine. But I see now that I didn’t weave that in to this version.
• There was an unclear part:
we emphasize these two first standalone word mentions.
Which shouldn’t be a problem now that the context/patch has been rewritten.
§ Cc
Linus Arver as the author of the example that this change touches.
This was more relevant on v1.
§ Link to v1
https://lore.kernel.org/git/[email protected]/#t
[1/9] doc: interpret-trailers: stop fixating on RFC 822 [2/9] doc: interpret-trailers: replace “lines” with “metadata” [3/9] doc: interpret-trailers: use “metadata” in Name as well [4/9] doc: interpret-trailers: not just for commit messages [5/9] doc: interpret-trailers: explain the format after the intro [6/9] doc: interpret-trailers: explain key format
[7/9] doc: interpret-trailers: add key format example [8/9] doc: interpret-trailers: commit to “trailer block” term [9/9] doc: intepret-trailers: document comment line treatment
Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++------ 1 file changed, 50 insertions(+), 18 deletions(-)
Interdiff against v1:
Documentation/git-interpret-trailers.adoc +51 -19
@@ -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_ key-value pairs 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
@@ -27,10 +33,7 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------ -the last two lines starting with `Signed-off-by` are trailers. These two -trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob). -The key must consist of only ASCII alphanumeric characters and hyphens -(`-`). The hyphens serve as interword separators. +the last two lines starting with `Signed-off-by` are trailers. This command reads commit messages from either the _<file>_ arguments or the standard input if no _<file>_ is specified.
@@ -84,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
@@ -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 <[email protected]> +$ 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]
base-commit: 5361983c075154725be47b65cca9a2421789e410
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 1/9 doc: interpret-trailers: stop fixating on RFC 822
From: Kristoffer Haugsbakk <[email protected]>
This command handles the trailers metadata format. But the command isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers.
This is overwrought; most people do not deal directly with email headers, and certainly not email RFCs.
Trailers are just key–value pairs that, like email headers, use colon as the separator. The format in its simplest form is easy to describe directly without comparing it to anything else; we will do that in the upcoming commit “explain the format after the intro”.
For now, let’s:
• remove the first mention of email headers;
• keep the second, innocuous comparison with email line folding in the middle; and
• remove the now-unneeded disclaimer that trailers do not share many of the features of RFC 822 email headers—there is no invitation to speculate that trailers would follow any other email format rules since we do not compare them directly any more.
***
Talking about trailers as an RFC 822/2822-like format seems to go back to the --fixes/Fixes: trailer topic,[1] the thread that precipitated this command and in turn the first trailer support in git(1) beyond adding s-o-b lines.
† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/
---
Notes (series):
v2:
• Use *** as a thematic break instead of ❦
• Change to “metadata” instead of “key–value pairs” since this series version adds a paragraph after this one where we dig into this term. And “metadata” describes the purpose of this format.
Documentation/git-interpret-trailers.adoc | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +3 -6
@@ -14,9 +14,9 @@ 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 _trailer_ lines at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject
@@ -107,9 +107,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`::
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 2/9 doc: interpret-trailers: replace “lines” with “metadata”
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We removed the initial comparison to email headers in the previous commit. Now the introduction paragraph just says “trailer lines”, and the only hint that this is metadata/structured information is the “otherwise free-form” phrase.
Let’s replace “lines” with “metadata” since that is their purpose. This also makes the introduction more consistent with how I chose to define trailers in the glossary:[1] “Key-value metadata”. (We will introduce “key–value” in the upcoming commit “explain the format after the intro”.)
† 1: 68e3c69e (Documentation/glossary: describe "trailer", 2024-11-17)
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailers metadata at the end of the otherwise free-form part of a commit message. For example, in the following commit message
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 3/9 doc: interpret-trailers: use “metadata” in Name as well
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We now since the previous commit introduce the format as “trailers metadata”. We can replace “structured information” with “metadata” in the “Name” section to be consistent.
While “structured information” does emphasize that the data is not loosely structured, we also say that this command adds to or parses this format. I don’t think that we need to emphasize that it is structured since clearly there is some structure there.
Both “metadata” and “structured information” can convey the same information. But “metadata” is shorter and easier to deploy since it’s just one word.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -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 --------
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 4/9 doc: interpret-trailers: not just for commit messages
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
This command doesn’t interface with commits directly. You can interpret or modify any kind of text, even though commit messages are the most relevant.
The git(1) suite also isn’t restricted to only direct commit support since git-tag(1) learned --trailer in 066cef77 (builtin/tag: add --trailer option, 2024-05-05)
Now, we already introduce the command in the “Name” section as dealing with commit messages as well. That is fine since that intro line needs to remain pretty short.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.adoc +2 -2
@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- Add or parse trailers metadata at the end of the otherwise -free-form part of a commit message. For example, in the following commit -message +free-form part of a commit message, or any other kind of text. +For example, in the following commit message ------------------------------------------------ subject
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 5/9 doc: interpret-trailers: explain the format after the intro
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
You need to read the entire “Description” section in order to understand the full trailer format. But there are many nuances, so that’s fine. As a starter though we have an introductory example.[1] That turns out to be crucial; the rest of this section talks about the mechanics of the command and only incidentally the format itself.
Now, although the example might arguably be self-explanatory, we can add a little preamble which defines the format in its simplest form as well as define the most important terms.
Note that we name the “blank line” rule since I want to use that term every time it comes up. It gets very mildly obfuscated if you call it a “blank line” in one place[2] and “empty (or whitespace-only) ...” in another one.[3]
We will define the format of the *key* in the next commit.
† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,
2023-06-15)
† 2: `Documentation/git-interpret-trailers.adoc:86` in
5361983c (The 22nd batch, 2026-03-27)
† 3: `Documentation/git-interpret-trailers.adoc:93` in
5361983c (The 22nd batch, 2026-03-27)---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +6 -1
@@ -16,7 +16,12 @@ DESCRIPTION ----------- Add or parse trailers metadata at the end of the otherwise free-form part of a commit message, or any other kind of text. -For example, in the following commit message + +A _trailer_ in its simplest form is a key-value pair with a colon as a +separator. 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
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 6/9 doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and only basing their trailer keys on the documentation examples.[1]
The previous commit provided us with an appropriate paragraph to describe the key format.
† 1: Technically they would then miss out on using digits in them since
all of the example keys just use letters and hyphens
---
Notes (series):
v2:
• Remove the “paint by numbers” reference after review (unclear)
• Add apropos footnote
• Tweak the paragraph about how we now have a context to describe this format
v1: [had a note about code spelunking (isalnum(3))]
Documentation/git-interpret-trailers.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +2 -1
@@ -18,7 +18,8 @@ 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. A _trailer block_ consists of one or more trailers. The +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
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 7/9 doc: interpret-trailers: add key format example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
All of the examples speak of the Happy Path where everything works as intended. But failure examples can also be instructive. Especially for explaining again, by example, the key format (see previous commit).
This also allows us to demonstrate trailer block detection with a concrete example.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
Documentation/git-interpret-trailers.adoc +23 -0
@@ -405,6 +405,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 <[email protected]> +$ 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]
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 8/9 doc: interpret-trailers: commit to “trailer block” term
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We chose to introduce the term “trailer block” into the documentation a few commits ago.[1] It is used in the code though, so it is not a newly invented term.
That term was useful to explain where the trailers are found (they *trail* the message). But it is also useful here, where we explain how trailers are added to existing messages, how trailer blocks are found (beyond the simple case in the introduction), and how the end of the message is found.
† 1: in commit “explain the format after the intro”
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-)
Documentation/git-interpret-trailers.adoc +14 -12
@@ -87,19 +87,21 @@ 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. - -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 +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 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). When reading trailers, there can be no whitespace before or inside the _<key>_, but any number of regular space and tab characters are allowed
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 9/9 doc: intepret-trailers: document comment line treatment
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Comment lines have always been ignored but this is not documented.
This is mostly for completeness since this is unlikely to catch anyone by surprise. But we really ought to be reasonably complete here since it’s the only documentation page that documents trailers.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++++ 1 file changed, 4 insertions(+)
Documentation/git-interpret-trailers.adoc +4 -0
@@ -103,6 +103,10 @@ 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 between the _<key>_ and the separator. There can be whitespaces before,
Signature · 1 line
2.53.0.32.gf6228eaf9cc
Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
Quoted 1 line
[PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
s/intepret-trailers/interpret-trailers/
Didn’t line up
Quoted 2 lines · On Mon, Apr 13, 2026, at 12:21, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
[snip]
Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
Quoted 5 lines · Kristoffer Haugsbakk
Quoted 1 line
[PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
s/intepret-trailers/interpret-trailers/
Didn’t line up
Yup, looking at [0/9], I agree.
Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
Quoted 9 lines · Junio C Hamano
Quoted 5 lines · Kristoffer Haugsbakk
Quoted 1 line
[PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
s/intepret-trailers/interpret-trailers/
Didn’t line up
Yup, looking at [0/9], I agree.
Junio fixed this up when applying. That’s why I didn’t send a new version.
A by-the-way for others here.
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
In reply to [email protected]Quoted 2 lines · On Mon, Apr 13, 2026, at 12:20, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
[snip]
Sorry to Ben here who I forgot to set on copy. :/
+Cc now.
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Quoted 7 lines · Kristoffer Haugsbakk
Quoted 2 lines · On Mon, Apr 13, 2026, at 12:20, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
[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/[email protected]/
Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 18 deletions(-)
Documentation/git-interpret-trailers.adoc +50 -18
@@ -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 <[email protected]> +$ 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]
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Overall looks good to me. Repeating a few points throughout the doc might create headaches if format restrictions are changed, but I think they are essential points worth repeating for now.
Quoted 56 lines · Junio C Hamano
Quoted 7 lines · Kristoffer Haugsbakk
Quoted 2 lines · On Mon, Apr 13, 2026, at 12:20, [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
[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/[email protected]/
Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 18 deletions(-)Documentation/git-interpret-trailers.adoc +10
-4@@ -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"`.
Documentation/git-interpret-trailers.adoc trailer.sign.key "Signed-off-by: " · line 94
Quoted 10 lines
Documentation/git-interpret-trailers.adoc +5
-4-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.
[not strictly related to this patch, but while we're here…]
Even in context, I find the original (and new) paragraph somewhat jarring. In "the new trailer," there's no antecedent for "the trailer", so which new trailer are we talking about? The previous paragraph is about "<key-alias>es" for --trailer="<key>: value".
We _could_ move this paragraph up one, so that it follows the paragraph on trailers being appended when given with --trailer.
Either way, adjusting "the new trailer" to "a new trailer" might feel better to me. Other suggestions welcome.
Quoted 63 lines
Documentation/git-interpret-trailers.adoc +35
-10-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 <[email protected]> +$ 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]
Signature · 1 line
D. Ben Knoble
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Quoted 3 lines · D. Ben Knoble
Overall looks good to me. Repeating a few points throughout the doc might create headaches if format restrictions are changed, but I think they are essential points worth repeating for now.
Thanks for taking a look again. :)
Quoted 22 lines
Quoted 4 lines
[snip]
Documentation/git-interpret-trailers.adoc +0
-0@@ -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"`.Documentation/git-interpret-trailers.adoc trailer.sign.key "Signed-off-by: " · line 94
Quoted 10 lines
Documentation/git-interpret-trailers.adoc +5
-4-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.[not strictly related to this patch, but while we're here…]
Even in context, I find the original (and new) paragraph somewhat jarring. In "the new trailer," there's no antecedent for "the trailer", so which new trailer are we talking about? The previous paragraph is about "<key-alias>es" for --trailer="<key>: value".
Quoted 5 lines
We _could_ move this paragraph up one, so that it follows the paragraph on trailers being appended when given with --trailer.
Either way, adjusting "the new trailer" to "a new trailer" might feel better to me. Other suggestions welcome.
The paragraph about new trailers originally came right after the separated-by sentence:[1]
By default, a '<token>=<value>' or '<token>:<value>' [...]
------------------------------------------------
token: value
------------------------------------------------
This means that the trimmed <token> and <value> will be separated by ': ' (one colon followed by one space).
By default the new trailer will appear [...]
† 1: dfd66ddf (Documentation: add documentation for 'git
interpret-trailers', 2014-10-13)
Nine years later in [2], a “For convenience, <token>” was added to that *existing paragraph:
[...]
': ' (one colon followed by one space). For convenience, the <token> can be a shortened string key (e.g., "sign") instead of the full string which should appear before the separator on the output (e.g., "Signed-off-by"). This can be configured using the 'trailer.<token>.key' configuration variable.
By default the new trailer will appear at the end [...]
† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)
A little later in [3], that part was split into its own paragraph—and expanded into two more blocks (source block and paragraph):
[...] <key> and <value> will be separated by ': ' (one colon followed by one space).
For convenience, a <keyAlias> can be configured to [...]
------------------------------------------------
key: value
------------------------------------------------
in your configuration, [...]
By default the new trailer will appear at the end [...]
† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
2023-09-07)
Quoted 2 lines
We _could_ move this paragraph up one, so that it follows the paragraph on trailers being appended when given with --trailer.
But going back to commit [1], there are two paragraphs that talk about how “By default” the new trailer will be appended to the end:
By default, a '<token>=<value>' or '<token>:<value>' argument given using --trailer will be appended after the existing trailers only if the last trailer has a different (<token>, <value>) pair (or if there is no existing trailer). The <token> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed <token> and <value> will appear in the message like this:
------------------------------------------------
token: value
------------------------------------------------
This means that the trimmed <token> and <value> will be separated by ': ' (one colon followed by one space).
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 after the commit message part of the ouput, and, if there is no line with only spaces at the end of the commit message part, one blank line will be added before the new trailer.
These two seem to overlap? They both talk about appending. Why does one talk about how specifically <token>/<key> and <value> will be treated when appended, then a later paragraph *also* says that it will be appended?
Here is a draft of this part of the doc. I have tried to consolidate these two “By default” paragrahs and be more explicit about what “the trailer” is. I have included one unchanged paragraph before and after for context.
***
Some configuration variables control the way the --trailer arguments are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers.
Let's consider new trailers added with --trailer.
By default, the new trailer will appear at the end of the trailer block. Also by default, this new trailer will only be added
if the last trailer is different to it.
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.
More concretely, this is how the new trailer is added: a <key>=<value> or <key>:<value> argument given using --trailer will be appended after the existing trailers. The _<key>_ and _<value>_ parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed _<key>_ and _<value>_ will appear in the output like this:
------------------------------------------------
key: value
------------------------------------------------
This means that the trimmed _<key>_ and _<value>_ will be separated by ":{nbsp}" (one colon followed by one space).
***
Quoted 8 lines
[snip]
Quoted 7 lines
Documentation/git-interpret-trailers.adoc +4
-2-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
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Quoted 9 lines · Kristoffer Haugsbakk
Quoted 3 lines · D. Ben Knoble
Overall looks good to me. Repeating a few points throughout the doc might create headaches if format restrictions are changed, but I think they are essential points worth repeating for now.
Thanks for taking a look again. :)
Thank you for working on it :)
Quoted 107 lines
Quoted 22 lines
Quoted 5 lines
[snip]
(quoted diff) +0
-0@@ -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".Documentation/git-interpret-trailers.adoc trailer.sign.key "Signed-off-by: " · line 94
Quoted 9 lines
Documentation/git-interpret-trailers.adoc +5
-4-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.[not strictly related to this patch, but while we're here…]
Even in context, I find the original (and new) paragraph somewhat jarring. In "the new trailer," there's no antecedent for "the trailer", so which new trailer are we talking about? The previous paragraph is about "<key-alias>es" for --trailer="<key>: value".
Quoted 5 lines
We _could_ move this paragraph up one, so that it follows the paragraph on trailers being appended when given with --trailer.
Either way, adjusting "the new trailer" to "a new trailer" might feel better to me. Other suggestions welcome.
The paragraph about new trailers originally came right after the separated-by sentence:[1]
By default, a '<token>=<value>' or '<token>:<value>' [...]
------------------------------------------------
token: value
------------------------------------------------This means that the trimmed <token> and <value> will be separated by
': '(one colon followed by one space).By default the new trailer will appear [...]
† 1:
dfd66ddf(Documentation: add documentation for 'gitinterpret-trailers', 2014-10-13)Nine years later in [2], a “For convenience, <token>” was added to that *existing paragraph:
[...]
': '(one colon followed by one space). For convenience, the <token> can be a shortened string key (e.g., "sign") instead of the full string which should appear before the separator on the output (e.g., "Signed-off-by"). This can be configured using the 'trailer.<token>.key' configuration variable.By default the new trailer will appear at the end [...]
† 2:
eda2c44c(doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)A little later in [3], that part was split into its own paragraph—and expanded into two more blocks (source block and paragraph):
[...] <key> and <value> will be separated by
': '(one colon followed by one space).For convenience, a <keyAlias> can be configured to [...]
------------------------------------------------
key: value
------------------------------------------------in your configuration, [...]
By default the new trailer will appear at the end [...]
† 3:
6ccbc667(trailer doc: <token> is a <key> or <keyAlias>, not both,2023-09-07)Quoted 2 lines
We _could_ move this paragraph up one, so that it follows the paragraph on trailers being appended when given with --trailer.
But going back to commit [1], there are two paragraphs that talk about how “By default” the new trailer will be appended to the end:
By default, a '<token>=<value>' or '<token>:<value>' argument given using
--trailerwill be appended after the existing trailers only if the last trailer has a different (<token>, <value>) pair (or if there is no existing trailer). The <token> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed <token> and <value> will appear in the message like this:------------------------------------------------
token: value
------------------------------------------------This means that the trimmed <token> and <value> will be separated by
': '(one colon followed by one space).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 after the commit message part of the ouput, and, if there is no line with only spaces at the end of the commit message part, one blank line will be added before the new trailer.
These two seem to overlap? They both talk about appending. Why does one talk about how specifically <token>/<key> and <value> will be treated when appended, then a later paragraph *also* says that it will be appended?
Quoted 4 lines
Here is a draft of this part of the doc. I have tried to consolidate these two “By default” paragrahs and be more explicit about what “the trailer” is. I have included one unchanged paragraph before and after for context.
I’ve read through the below a few times, and I don’t really have much to add for now :) I think that’s a fine improvement.
Whether you roll that into this patch series or wait until the dust settles is up to you.
Quoted 39 lines
***
Some configuration variables control the way the
--trailerarguments are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers.Let's consider new trailers added with
--trailer.
By default, the new trailer will appear at the end of the trailer block. Also by default, this new trailer will only be added
if the last trailer is different to it.
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.More concretely, this is how the new trailer is added: a
<key>=<value>or<key>:<value>argument given using--trailerwill be appended after the existing trailers. The _<key>_ and _<value>_ parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed _<key>_ and _<value>_ will appear in the output like this:------------------------------------------------
key: value
------------------------------------------------This means that the trimmed _<key>_ and _<value>_ will be separated by "
:{nbsp}" (one colon followed by one space).***
Quoted 8 lines
[snip]
Quoted 7 lines
Documentation/git-interpret-trailers.adoc +4
-2-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
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Quoted 18 lines · Ben Knoble
Quoted 8 lines · Kristoffer Haugsbakk
Quoted 3 lines · D. Ben Knoble
Overall looks good to me. Repeating a few points throughout the doc might create headaches if format restrictions are changed, but I think they are essential points worth repeating for now.
Thanks for taking a look again. :)
Thank you for working on it :)
Quoted 6 lines
[snip]
Here is a draft of this part of the doc. I have tried to consolidate these two “By default” paragrahs and be more explicit about what “the trailer” is. I have included one unchanged paragraph before and after for context.
Quoted 5 lines
I’ve read through the below a few times, and I don’t really have much to add for now :) I think that’s a fine improvement.
Whether you roll that into this patch series or wait until the dust settles is up to you.
Many thanks!
Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Quoted 9 lines · Kristoffer Haugsbakk
Quoted 7 lines
[snip]
I’ve read through the below a few times, and I don’t really have much to add for now :) I think that’s a fine improvement.
Whether you roll that into this patch series or wait until the dust settles is up to you.
Many thanks!
Sorry. I forgot to add: the plan right now is to weave it into this series.
v3 cover doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.
To that end, an overview of the changes:
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain the “key” format, and add a new example
• Patch 8 [new]: join some existing paragraphs that are about the same theme since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in patch 5 later in the doc
• Patch 10 [new]: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behavior
§ Changes in v3
I followed up on D. Ben’s suggestion about thematic paragraphs (patch 8).
I also made a new change as a knock-on to patch 8. That’s patch 10.
I also changed patch 11 (formerly 10): moved it out into its own section.
See the patches for details. Look for “v3” in the patch Notes.
§ Apologies for very cross-referenced commit messages
Like I wrote on v2.
Here one thing lead to another,
And in the process I had to make changes that necessitated *other changes* as a knock-on effect. Shuffle some text, need to reshuffle three paragraphs later for consistency. And rather than piling on “While at it”/“Also”, I chose to try to make focused commits. (Which is how an idea to explain that trailer keys are alphanum/hyhens-only became eleven patches.)
But in order to follow up on related items I needed to refer to both future and previous commits. And in the process I abandoned the usual “in an upcoming commit”/“in a previous commit” in favor of perhaps a gratingly precise “commit <subject without area>”, e.g.:
The format in its simplest form is easy to describe directly without comparing it to anything else; we will do that in the upcoming commit “explain the format after the intro”.
and,
This also makes the introduction more consistent with how I chose to define trailers in the glossary:[1] “Key-value metadata”. (We will introduce “key–value” in the upcoming commit “explain the format after the intro”.)
§ Cc
(see v2)
§ In-reply-to: v1
§ Link to v2
https://lore.kernel.org/git/[email protected]/
[01/11] doc: interpret-trailers: stop fixating on RFC 822 [02/11] doc: interpret-trailers: replace “lines” with “metadata” [03/11] doc: interpret-trailers: use “metadata” in Name as well [04/11] doc: interpret-trailers: not just for commit messages [05/11] doc: interpret-trailers: explain the format after the intro [06/11] doc: interpret-trailers: explain key format [07/11] doc: interpret-trailers: add key format example [08/11] doc: interpret-trailers: join new-trailers again [09/11] doc: interpret-trailers: commit to “trailer block” term [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs [11/11] doc: interpret-trailers: document comment line treatment
Documentation/git-interpret-trailers.adoc | 92 ++++++++++++++++------- 1 file changed, 66 insertions(+), 26 deletions(-)
Interdiff against v2:
Documentation/git-interpret-trailers.adoc +34 -26
@@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers. -By default, a `<key>=<value>` or `<key>:<value>` argument given -using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed -to remove starting and trailing whitespace, and the resulting trimmed -_<key>_ and _<value>_ will appear in the output like this: +Let's consider new trailers added with `--trailer`. +By default, the new trailer will appear at the end of the trailer block. +Also by default, this new trailer will only be added +if the last trailer is different to it. +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. + +More concretely, this is how the new trailer is added: a `<key>=<value>` +or `<key>:<value>` argument given using `--trailer` will be appended +after the existing trailers. The _<key>_ and _<value>_ parts will be +trimmed to remove starting and trailing whitespace, and the resulting +trimmed _<key>_ and _<value>_ will appear in the output like this: ------------------------------------------------ key: value
@@ -74,6 +82,16 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). +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 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). + For convenience, a _<key-alias>_ can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the `trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
@@ -87,26 +105,6 @@ 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 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 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 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 between the _<key>_ and the separator. There can be whitespaces before,
@@ -119,6 +117,16 @@ key: This is a very long value, with spaces and newlines in it. ------------------------------------------------ +OTHER RULES +----------- + +What was covered in the previous section are the rules that are relevant +for regular use. The following points are included for completeness. + +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. + OPTIONS ------- `--in-place`::
Range-diff against v2:
1: e5d58237bc2 = 1: e5d58237bc2 doc: interpret-trailers: stop fixating on RFC 822 2: 5ddd39bf157 = 2: 5ddd39bf157 doc: interpret-trailers: replace “lines” with “metadata” 3: 9f0227a1978 = 3: 9f0227a1978 doc: interpret-trailers: use “metadata” in Name as well 4: 4cb26810d4e = 4: 4cb26810d4e doc: interpret-trailers: not just for commit messages 5: 196c91bebe3 = 5: 196c91bebe3 doc: interpret-trailers: explain the format after the intro 6: 688ea55599a = 6: 688ea55599a doc: interpret-trailers: explain key format 7: e6eafbd641f = 7: e6eafbd641f doc: interpret-trailers: add key format example -: ----------- > 8: 8849ace33e6 doc: interpret-trailers: join new-trailers again 8: f14d641309c ! 9: 8323b84e134 doc: interpret-trailers: commit to “trailer block” term
@@ Commit message
## Documentation/git-interpret-trailers.adoc ##
-@@ Documentation/git-interpret-trailers.adoc: 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". +@@ Documentation/git-interpret-trailers.adoc: key: value
+ This means that the trimmed _<key>_ and _<value>_ will be separated by
+ ":{nbsp}" (one colon followed by one space).
-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
@@ Documentation/git-interpret-trailers.adoc: trailer.sign.key "Signed-off-by: "
+the last non-whitespace lines before a line that starts with --- +(followed by a space or the end of the line).
- When reading trailers, there can be no whitespace before or inside the
- _<key>_, but any number of regular space and tab characters are allowed
+ For convenience, a _<key-alias>_ can be configured to make using --trailer
+ shorter to type on the command line. This can be configured using the
-: ----------- > 10: c7495c3b39e doc: interpret-trailers: rewrite new-trailers paragraphs 9: 78125ab39f1 ! 11: fc38e8660f0 doc: intepret-trailers: document comment line treatment
@@ Metadata
Author: Kristoffer Haugsbakk <[email protected]>
## Commit message ##
- doc: intepret-trailers: document comment line treatment
+ doc: interpret-trailers: document comment line treatment
Comment lines have always been ignored but this is not documented.
@@ Commit message
## Documentation/git-interpret-trailers.adoc ##
-@@ Documentation/git-interpret-trailers.adoc: 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).
+@@ Documentation/git-interpret-trailers.adoc: key: This is a very long value, with spaces and
+ newlines in it.
+ ------------------------------------------------
++OTHER RULES
++-----------
++
++What was covered in the previous section are the rules that are relevant ++for regular use. The following points are included for completeness. ++
+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
- between the _<key>_ and the separator. There can be whitespaces before,
+ OPTIONS
+ -------
+ --in-place::
base-commit: 5361983c075154725be47b65cca9a2421789e410
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 1/11 doc: interpret-trailers: stop fixating on RFC 822
From: Kristoffer Haugsbakk <[email protected]>
This command handles the trailers metadata format. But the command isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers.
This is overwrought; most people do not deal directly with email headers, and certainly not email RFCs.
Trailers are just key–value pairs that, like email headers, use colon as the separator. The format in its simplest form is easy to describe directly without comparing it to anything else; we will do that in the upcoming commit “explain the format after the intro”.
For now, let’s:
• remove the first mention of email headers;
• keep the second, innocuous comparison with email line folding in the middle; and
• remove the now-unneeded disclaimer that trailers do not share many of the features of RFC 822 email headers—there is no invitation to speculate that trailers would follow any other email format rules since we do not compare them directly any more.
***
Talking about trailers as an RFC 822/2822-like format seems to go back to the --fixes/Fixes: trailer topic,[1] the thread that precipitated this command and in turn the first trailer support in git(1) beyond adding s-o-b lines.
† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/
---
Notes (series):
v2:
• Use *** as a thematic break instead of ❦
• Change to “metadata” instead of “key–value pairs” since this series version adds a paragraph after this one where we dig into this term. And “metadata” describes the purpose of this format.
Documentation/git-interpret-trailers.adoc | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +3 -6
@@ -14,9 +14,9 @@ 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 _trailer_ lines at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject
@@ -107,9 +107,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`::
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 2/11 doc: interpret-trailers: replace “lines” with “metadata”
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We removed the initial comparison to email headers in the previous commit. Now the introduction paragraph just says “trailer lines”, and the only hint that this is metadata/structured information is the “otherwise free-form” phrase.
Let’s replace “lines” with “metadata” since that is their purpose. This also makes the introduction more consistent with how I chose to define trailers in the glossary:[1] “Key-value metadata”. (We will introduce “key–value” in the upcoming commit “explain the format after the intro”.)
† 1: 68e3c69e (Documentation/glossary: describe "trailer", 2024-11-17)
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailers metadata at the end of the otherwise free-form part of a commit message. For example, in the following commit message
Signature · 1 line
2.54.0.22.g9e26862b904
Re: [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”
Documentation/git-interpret-trailers.adoc git interpret-trailers [--in-place] [--trim-empty] · line 17
Quoted 11 lines · kristofferhaugsbakk
Documentation/git-interpret-trailers.adoc +1
-1@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailers metadata at the end of the otherwise
fwiw, I think "trailer metadata" reads more naturally.
Re: [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”
Quoted 8 lines · Matt Hunter
Documentation/git-interpret-trailers.adoc git interpret-trailers [--in-place] [--trim-empty] · line 17
Quoted 5 lines · kristofferhaugsbakk
[snip]
DESCRIPTION
-----------Documentation/git-interpret-trailers.adoc +1
-1-Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailers metadata at the end of the otherwisefwiw, I think "trailer metadata" reads more naturally.
You’re right that your version reads more naturally. I went back and forth on this.
1. We’re introducing the jargon, and the format is often discussed as plural “trailers”, with its constituent parts being singular “trailer”
2. What this replaces uses “trailer”, but it rescues the plural mood with “lines”
3. This is very soon going to go into the constituent parts, including each trailer, so we’re contrasting the concept name (trailers) with its parts
But I think your version is overall better. It reads better and there is no way to confuse “trailer metadata” (trailers as a collection) with just a single “trailer”.
Re: [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”
Quoted 10 lines · Kristoffer Haugsbakk
Quoted 8 lines · Matt Hunter
Documentation/git-interpret-trailers.adoc git interpret-trailers [--in-place] [--trim-empty] · line 17
Quoted 5 lines · kristofferhaugsbakk
[snip]
DESCRIPTION
-----------Documentation/git-interpret-trailers.adoc +1
-1-Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailers metadata at the end of the otherwisefwiw, I think "trailer metadata" reads more naturally.
Quoted 2 lines
You’re right that your version reads more naturally. I went back and forth on this.
After reading your points, I started debating the grammatical correctness of it to myself too. Though I think I stand by my original knee-jerk response.
Quoted 10 lines
1. We’re introducing the jargon, and the format is often discussed as plural “trailers”, with its constituent parts being singular “trailer”
2. What this replaces uses “trailer”, but it rescues the plural mood with “lines”
3. This is very soon going to go into the constituent parts, including each trailer, so we’re contrasting the concept name (trailers) with its parts
Quoted 3 lines
But I think your version is overall better. It reads better and there is no way to confuse “trailer metadata” (trailers as a collection) with just a single “trailer”.
Yes, "metadata" reads as a hint to me that interpret-trailers works with the overall trailer block too.
Another thought I had after seeing this again is that the text could just say "Add or parse trailers at the end ...", but "metadata" is a lot more useful, since it's an introduction to what trailers _are_. So the patch is an improvement over the original context imo.
PATCH v3 3/11 doc: interpret-trailers: use “metadata” in Name as well
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We now since the previous commit introduce the format as “trailers metadata”. We can replace “structured information” with “metadata” in the “Name” section to be consistent.
While “structured information” does emphasize that the data is not loosely structured, we also say that this command adds to or parses this format. I don’t think that we need to emphasize that it is structured since clearly there is some structure there.
Both “metadata” and “structured information” can convey the same information. But “metadata” is shorter and easier to deploy since it’s just one word.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -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 --------
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 4/11 doc: interpret-trailers: not just for commit messages
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
This command doesn’t interface with commits directly. You can interpret or modify any kind of text, even though commit messages are the most relevant.
The git(1) suite also isn’t restricted to only direct commit support since git-tag(1) learned --trailer in 066cef77 (builtin/tag: add --trailer option, 2024-05-05)
Now, we already introduce the command in the “Name” section as dealing with commit messages as well. That is fine since that intro line needs to remain pretty short.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.adoc +2 -2
@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- Add or parse trailers metadata at the end of the otherwise -free-form part of a commit message. For example, in the following commit -message +free-form part of a commit message, or any other kind of text. +For example, in the following commit message ------------------------------------------------ subject
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 5/11 doc: interpret-trailers: explain the format after the intro
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
You need to read the entire “Description” section in order to understand the full trailer format. But there are many nuances, so that’s fine. As a starter though we have an introductory example.[1] That turns out to be crucial; the rest of this section talks about the mechanics of the command and only incidentally the format itself.
Now, although the example might arguably be self-explanatory, we can add a little preamble which defines the format in its simplest form as well as define the most important terms.
Note that we name the “blank line” rule since I want to use that term every time it comes up. It gets very mildly obfuscated if you call it a “blank line” in one place[2] and “empty (or whitespace-only) ...” in another one.[3]
We will define the format of the *key* in the next commit.
† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,
2023-06-15)
† 2: `Documentation/git-interpret-trailers.adoc:86` in
5361983c (The 22nd batch, 2026-03-27)
† 3: `Documentation/git-interpret-trailers.adoc:93` in
5361983c (The 22nd batch, 2026-03-27)---
Notes (series):
v2: [new]
• PS: Suggested here: https://lore.kernel.org/git/[email protected]/#t
• (My tardiness on this topic has made these reminders necessary,
if only for my own reference)
Documentation/git-interpret-trailers.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +6 -1
@@ -16,7 +16,12 @@ DESCRIPTION ----------- Add or parse trailers metadata at the end of the otherwise free-form part of a commit message, or any other kind of text. -For example, in the following commit message + +A _trailer_ in its simplest form is a key-value pair with a colon as a +separator. 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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 6/11 doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and only basing their trailer keys on the documentation examples.[1]
The previous commit provided us with an appropriate paragraph to describe the key format.
† 1: Technically they would then miss out on using digits in them since
all of the example keys just use letters and hyphens
---
Notes (series):
v2:
• PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/
• Remove the “paint by numbers” reference after review (unclear)
• Add apropos footnote
• Tweak the paragraph about how we now have a context to describe
this format
v1: [had a note about code spelunking (isalnum(3))]
Documentation/git-interpret-trailers.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +2 -1
@@ -18,7 +18,8 @@ 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. A _trailer block_ consists of one or more trailers. The +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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 7/11 doc: interpret-trailers: add key format example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
All of the examples speak of the Happy Path where everything works as intended. But failure examples can also be instructive. Especially for explaining again, by example, the key format (see previous commit).
This also allows us to demonstrate trailer block detection with a concrete example.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
Documentation/git-interpret-trailers.adoc +23 -0
@@ -405,6 +405,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 <[email protected]> +$ 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]
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 8/11 doc: interpret-trailers: join new-trailers again
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
There are three trailers that talk about how a new trailer is added. But the first one is separated from the other two by two paragraphs about how key-alias can make using --trailer more convenient. This short how-to does not follow thematically from the previous paragraph, and can wait until we have fully described how a new trailer is added. So let’s move the three paragraphs about the new-trailer topic together and move the how-to paragraphs after that.
***
Let’s now review the history of the document. Even if the document is not quite correct in its current state, just doing the apparently obvious edit without considering the history does not respect the effort that went into changing the document in the past.
These three paragraphs were originally next to each other, in the first version of the doc.[1] But extra sentences about this how-to topic was added to the first paragraph nine years later:[2]
[...]
': ' (one colon followed by one space). For convenience, the <token> can be a shortened string key (e.g., "sign") instead of the full string which should [...]
And then it was split into it’s own paragraph a little later.[3]
This evolution shows, in my opinion, that this how-to never followed thematically from the existing topic. Which means that there is nothing that was potentially lost to time that we need to restore or respect.
† 1: dfd66ddf (Documentation: add documentation for 'git
interpret-trailers', 2014-10-13)
† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)
† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
2023-09-07)---
Notes (series):
v3: [new]
• Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/
• Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-)
Documentation/git-interpret-trailers.adoc +13 -13
@@ -74,19 +74,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -For convenience, a _<key-alias>_ can be configured to make using `--trailer` -shorter to type on the command line. This can be configured using the -`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix -of the full _<key>_ string, although case sensitivity does not matter. For -example, if you have - ------------------------------------------------- -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
@@ -101,6 +88,19 @@ 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). +For convenience, a _<key-alias>_ can be configured to make using `--trailer` +shorter to type on the command line. This can be configured using the +`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix +of the full _<key>_ string, although case sensitivity does not matter. For +example, if you have + +------------------------------------------------ +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"`. + When reading trailers, there can be no whitespace before or inside the _<key>_, but any number of regular space and tab characters are allowed between the _<key>_ and the separator. There can be whitespaces before,
Signature · 1 line
2.54.0.22.g9e26862b904
Re: [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again
Quoted 4 lines · On Wed, Jun 10, 2026 at 5:24 PM <[email protected]> wrote:
From: Kristoffer Haugsbakk <[email protected]>
There are three trailers that talk about how a new trailer is added.
3 "paragraphs"? :)
Quoted 6 lines
But the first one is separated from the other two by two paragraphs about how
key-aliascan make using--trailermore convenient. This short how-to does not follow thematically from the previous paragraph, and can wait until we have fully described how a new trailer is added. So let’s move the three paragraphs about the new-trailer topic together and move the how-to paragraphs after that.
[snip]
Re: [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again
Quoted 7 lines · D. Ben Knoble
Quoted 4 lines · On Wed, Jun 10, 2026 at 5:24 PM <[email protected]> wrote:
From: Kristoffer Haugsbakk <[email protected]>
There are three trailers that talk about how a new trailer is added.
3 "paragraphs"? :)
Oh doh! Thanks. ;)
Quoted 1 line
[snip]
PATCH v3 9/11 doc: interpret-trailers: commit to “trailer block” term
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We chose to introduce the term “trailer block” into the documentation a few commits ago.[1] It is used in the code though, so it is not a newly invented term.
That term was useful to explain where the trailers are found (they *trail* the message). But it is also useful here, where we explain how trailers are added to existing messages, how trailer blocks are found (beyond the simple case in the introduction), and how the end of the message is found.
† 1: in commit “explain the format after the intro”
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-)
Documentation/git-interpret-trailers.adoc +14 -12
@@ -74,19 +74,21 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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. - -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 +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 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). For convenience, a _<key-alias>_ can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 10/11 doc: interpret-trailers: rewrite new-trailers paragraphs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Two commits ago we moved new-trailers paragraph next to each other. But there is something curious about two of them:
By default the new trailer will appear at the end of the trailer block. [...]
Then a source block and a paragraph later:
By default, a <key>=<value> or <key>:<value> argument given using --trailer will be appended after the existing trailers only if [...]
Why are there two paragraphs that talk about how “By default” a trailer will be appended?
We can make these paragraphs flow better, and with a more distinct character each, by dividing the flow like this:
1. Declare that we are about to talk about --trailer appending
2. Explain the default behavior
3. Explain how this affects the trailer block
4. Then state the same thing (“More concretely”) in concrete terms with placeholders
---
Notes (series):
v3: [new]
• Based on draft: https://lore.kernel.org/git/[email protected]/
• See msg:
Two commits ago we moved new-trailers paragraph next to each other.
This commit here might fit better one step back. So that it becomes the commit right after. But I can deal with that commit movement if this change is accepted. For now I didn’t bother.
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-)
Documentation/git-interpret-trailers.adoc +14 -12
@@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers. -By default, a `<key>=<value>` or `<key>:<value>` argument given -using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed -to remove starting and trailing whitespace, and the resulting trimmed -_<key>_ and _<value>_ will appear in the output like this: +Let's consider new trailers added with `--trailer`. +By default, the new trailer will appear at the end of the trailer block. +Also by default, this new trailer will only be added +if the last trailer is different to it. +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. + +More concretely, this is how the new trailer is added: a `<key>=<value>` +or `<key>:<value>` argument given using `--trailer` will be appended +after the existing trailers. The _<key>_ and _<value>_ parts will be +trimmed to remove starting and trailing whitespace, and the resulting +trimmed _<key>_ and _<value>_ will appear in the output like this: ------------------------------------------------ key: value
@@ -74,12 +82,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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 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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v3 11/11 doc: interpret-trailers: document comment line treatment
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Comment lines have always been ignored but this is not documented.
This is mostly for completeness since this is unlikely to catch anyone by surprise. But we really ought to be reasonably complete here since it’s the only documentation page that documents trailers.
---
Notes (series):
v3:
• Msg: finally fix area
• Demote this point to its own “other rules” section, out of the main running text. It is not important enough for the main text.
• Since writing this I have realized that we can go into that long
# ----- >8 ----
Commit message separator scissor line, maybe other things. But I stop short here. These things are even less likely to become a problem for anyone. And maybe we’ll add them later?
v2: [new]
Documentation/git-interpret-trailers.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+)
Documentation/git-interpret-trailers.adoc +10 -0
@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and newlines in it. ------------------------------------------------ +OTHER RULES +----------- + +What was covered in the previous section are the rules that are relevant +for regular use. The following points are included for completeness. + +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. + OPTIONS ------- `--in-place`::
Signature · 1 line
2.54.0.22.g9e26862b904
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
In reply to [email protected]Quoted 9 lines · [email protected] writes:
Interdiff against v2:
Documentation/git-interpret-trailers.adoc +0
-0@@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers.
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 66
Quoted 10 lines
Documentation/git-interpret-trailers.adoc +4
-6-By default, a `<key>=<value>` or `<key>:<value>` argument given -using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed -to remove starting and trailing whitespace, and the resulting trimmed -_<key>_ and _<value>_ will appear in the output like this: +Let's consider new trailers added with `--trailer`. +By default, the new trailer will appear at the end of the trailer block. +Also by default, this new trailer will only be added +if the last trailer is different to it.
The new text is more succinct here.
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 70
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +4
-0+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.
If you want to stress that a line with only whitespaces on it does not count as a blank line for the purpose of this paragraph, you can consistently say "an empty line" withotu saying "a blank line", and you do not need to have "(specifically an empty lline)" there.
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 76
Quoted 5 lines
Documentation/git-interpret-trailers.adoc +5
-0+More concretely, this is how the new trailer is added: a `<key>=<value>` +or `<key>:<value>` argument given using `--trailer` will be appended +after the existing trailers. The _<key>_ and _<value>_ parts will be +trimmed to remove starting and trailing whitespace, and the resulting +trimmed _<key>_ and _<value>_ will appear in the output like this:
"More concretely" here feels a bit out of place, as the three paragraphs we saw so far aren't really progression of the same thing. First we saw when a new trailer line is added, second we learned that an extra empty line may be added in addition to the new trailer line. What we are about to mention is orthogonal: how each trailer line would look like. There is no more or less concrete about it.
Documentation/git-interpret-trailers.adoc key: value · line 86
Quoted 8 lines
Documentation/git-interpret-trailers.adoc +2
-0------------------------------------------------ key: value@@ -74,6 +82,16 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). +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)
"Concretely, that is a" -> "A trailer block is a".
Documentation/git-interpret-trailers.adoc key: value · line 89
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +3
-0+is all trailers, or (ii) contains at least one Git-generated or +user-configured trailer and consists of at +least 25% trailers.
Hmph, isn't (i) a narrow subset of (ii)?
Documentation/git-interpret-trailers.adoc key: value · line 91
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+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)
"at the end the the message" -> "at the end of the commit log message", and "the input" -> "the message", probably.
The latter is because not everybody is "parsing" the message to futz with trailers, using the message as "input", and some are "writing out" the message, using it as "output".
Documentation/git-interpret-trailers.adoc key: value · line 93
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+the last non-whitespace lines before a line that starts with `---` +(followed by a space or the end of the line).
OK.
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
Quoted 5 lines · Junio C Hamano
Documentation/git-interpret-trailers.adoc
Quoted 3 lines · [email protected] writes:
Interdiff against v2:
Documentation/git-interpret-trailers.adoc +0
-0
By the way, what I queued last night was missing [10/11] as I used "b4 am" to grab the latest thread messages by giving the message-id of the cover letter, but somehow [10/11] had a bogus value in the e-mail header.
Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs
Date: Wed, 10 Jun 2026 23:21:28 +0200
Message-ID: <>
X-Mailer: git-send-email 2.54.0.22.g9e26862b904So, I reverted to the old and battle tested way to pick these 11 messages manually in my newsreader to replace the topic.
If you have a chance, could you investigate where the send-out process went wrong and gave one message a bogus ID? I am worried if you may have triggered a bug in send-email, in which case we would want to fix it to avoid hurting other users.
Thanks.
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
Quoted 19 lines · Junio C Hamano
Quoted 5 lines · Junio C Hamano
Documentation/git-interpret-trailers.adoc
Quoted 3 lines · [email protected] writes:
Interdiff against v2:
Documentation/git-interpret-trailers.adoc +0
-0By the way, what I queued last night was missing [10/11] as I used "b4 am" to grab the latest thread messages by giving the message-id of the cover letter, but somehow [10/11] had a bogus value in the e-mail header.
Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite
new-trailers paragraphsDate: Wed, 10 Jun 2026 23:21:28 +0200 Message-ID: <> X-Mailer: git-send-email 2.54.0.22.g9e26862b904
Quoted 7 lines
So, I reverted to the old and battle tested way to pick these 11 messages manually in my newsreader to replace the topic.
If you have a chance, could you investigate where the send-out process went wrong and gave one message a bogus ID? I am worried if you may have triggered a bug in send-email, in which case we would want to fix it to avoid hurting other users.
I’ll investigate. It’s 99.99% chance a problem on my end, created by me.
Sorry for the trouble!
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
Quoted 17 lines · Kristoffer Haugsbakk
Quoted 17 lines
Quoted 2 lines
Quoted 2 lines
[snip]
...By the way, what I queued last night was missing [10/11] as I used "b4 am" to grab the latest thread messages by giving the message-id of the cover letter, but somehow [10/11] had a bogus value in the e-mail header.
Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite
new-trailers paragraphsDate: Wed, 10 Jun 2026 23:21:28 +0200 Message-ID: <> X-Mailer: git-send-email 2.54.0.22.g9e26862b904So, I reverted to the old and battle tested way to pick these 11 messages manually in my newsreader to replace the topic.
Quoted 8 lines
Quoted 4 lines
If you have a chance, could you investigate where the send-out process went wrong and gave one message a bogus ID? I am worried if you may have triggered a bug in send-email, in which case we would want to fix it to avoid hurting other users.
I’ll investigate. It’s 99.99% chance a problem on my end, created by me.
Sorry for the trouble!
It was as stupid and embarrassing as it looked at first glance. A search-and-replace on the format-patch output which was missing a target value.
I’m very sorry again.
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
In reply to Junio C HamanoQuoted 10 lines · Junio C Hamano
[snip]
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 70
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +4
-0+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.If you want to stress that a line with only whitespaces on it does not count as a blank line for the purpose of this paragraph, you can consistently say "an empty line" withotu saying "a blank line", and you do not need to have "(specifically an empty lline)" there.
Okay, I’ll make it shorter.
It felt too long for a simple concept indeed.
Quoted 13 lines
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 76
Quoted 6 lines
Documentation/git-interpret-trailers.adoc +5
-0+More concretely, this is how the new trailer is added: a `<key>=<value>` +or `<key>:<value>` argument given using `--trailer` will be appended +after the existing trailers. The _<key>_ and _<value>_ parts will be +trimmed to remove starting and trailing whitespace, and the resulting +trimmed _<key>_ and _<value>_ will appear in the output like this:"More concretely" here feels a bit out of place, as the three paragraphs we saw so far aren't really progression of the same thing. First we saw when a new trailer line is added, second we learned that an extra empty line may be added in addition to the new trailer line. What we are about to mention is orthogonal: how each trailer line would look like. There is no more or less concrete about it.
Yeah, I think I see. I thought this would be continuation into the more nuts and bolts of it, where we move from discussing the concepts to the concrete placeholders, so to speak.
I thought I needed a phrase to connect the paragraphs. But now I don’t think I do. Just dropping that phrase:
Let's consider new trailers added with --trailer.
By default, the new trailer will appear at the end of the trailer block. Also by default, this new trailer will only be added
if the last trailer is different to it.
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.
This is how the new trailer is added: a <key>=<value> or <key>:<value> argument given using --trailer will be appended after the existing trailers. The _<key>_ and _<value>_ parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed _<key>_ and _<value>_ will appear in the output like this:
And it still flows.
Quoted 11 lines
Documentation/git-interpret-trailers.adoc key: value · line 86
Quoted 9 lines
------------------------------------------------
key: valueDocumentation/git-interpret-trailers.adoc +2
-0@@ -74,6 +82,16 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). +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)"Concretely, that is a" -> "A trailer block is a".
Yeah. That seems simpler.
Replacing “that” with what it represents, namely “A trailer block”.
Sometimes just repeating the noun can feel stuttery, like the sentences don’t flow. But there is enough variation here; the previous sentence ends with “the trailer block” (definitive), and the next sentence takes a step back and talks about the indefinitive (a trailer block).
Quoted 6 lines
Documentation/git-interpret-trailers.adoc key: value · line 89
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +3
-0+is all trailers, or (ii) contains at least one Git-generated or +user-configured trailer and consists of at +least 25% trailers.Hmph, isn't (i) a narrow subset of (ii)?
Well, this text modulo a grammatical fix goes back all the way to the implementation of the 25% rule in 14624506 (trailer: allow non-trailers in trailer block, 2016-10-21).
But I don’t see how either one is a subset of the other. With (i) I just need valid trailers. With (ii) I need at least one “Git-generated” trailer (or (cherry picked from I think), i.e. as soon as a non-trailer line has infected the prospective block.
You could have respectively:
i. Only trailers but none are configured
ii. One configured trailer and one comment line
I don’t see how one can subsume the other.
Quoted 6 lines
Documentation/git-interpret-trailers.adoc key: value · line 91
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +2
-0+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)"at the end the the message" -> "at the end of the commit log message", and "the input" -> "the message", probably.
Okay, there is both a “the the” as well as missing “of”.
As to “*commit* message”: my first instinct was that the text might as well talk about just “message” throughout, since we establish at the beginning that a commit message is *one* application (and the main one) but isn’t necessarily the only one (tag messages these days, in fact). But now I see that we already use “commit message” throughout, so it is indeed best to stick with that here.
Quoted 3 lines
The latter is because not everybody is "parsing" the message to futz with trailers, using the message as "input", and some are "writing out" the message, using it as "output".
I don’t understand this part. This is supposed to be prosaic. The input is the data on the standard input. And of that data the message is a subset, for example and probably most notably with the git-format-patch(1) format.
Now, we could define what “the commit message” is in terms of “the message”. But those terms are so close, it might look like you are restating “commit message” but just dropping “commit” because it is clear from context now.
For comparison this is the paragraph on master (commit 0fae78c9).
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 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).
Quoted 4 lines
Documentation/git-interpret-trailers.adoc key: value · line 93
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+the last non-whitespace lines before a line that starts with `---` +(followed by a space or the end of the line).OK.
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
"Kristoffer Haugsbakk" <[email protected]> writes:
I was reviewing the draft of the What's Cooking report and noticed that this topic is among a handful of stalled efforts going nowhere.
Quoted 9 lines
Quoted 4 lines
If you want to stress that a line with only whitespaces on it does not count as a blank line for the purpose of this paragraph, you can consistently say "an empty line" withotu saying "a blank line", and you do not need to have "(specifically an empty lline)" there.
Okay, I’ll make it shorter.
It felt too long for a simple concept indeed.
...
And it has been more than a month since we discussed this topic the last time. Will we see an update anytime soon? If not, let me mark the topic to be discarded in my draft of the whats-cooking report.
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
Quoted 12 lines · Junio C Hamano
"Kristoffer Haugsbakk" <[email protected]> writes:
I was reviewing the draft of the What's Cooking report and noticed that this topic is among a handful of stalled efforts going nowhere.
Quoted 7 lines
Quoted 4 lines
If you want to stress that a line with only whitespaces on it does not count as a blank line for the purpose of this paragraph, you can consistently say "an empty line" withotu saying "a blank line", and you do not need to have "(specifically an empty lline)" there.
Okay, I’ll make it shorter.
Quoted 7 lines
Quoted 2 lines
It felt too long for a simple concept indeed.
...And it has been more than a month since we discussed this topic the last time. Will we see an update anytime soon? If not, let me mark the topic to be discarded in my draft of the whats-cooking report.
I’ve posted the next version now.
Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
Quoted 16 lines · Kristoffer Haugsbakk
Quoted 15 lines · Junio C Hamano
"Kristoffer Haugsbakk" <[email protected]> writes:
I was reviewing the draft of the What's Cooking report and noticed that this topic is among a handful of stalled efforts going nowhere.
Quoted 9 lines
Quoted 4 lines
If you want to stress that a line with only whitespaces on it does not count as a blank line for the purpose of this paragraph, you can consistently say "an empty line" withotu saying "a blank line", and you do not need to have "(specifically an empty lline)" there.
Okay, I’ll make it shorter.
It felt too long for a simple concept indeed.
...
Quoted 6 lines
Quoted 4 lines
And it has been more than a month since we discussed this topic the last time. Will we see an update anytime soon? If not, let me mark the topic to be discarded in my draft of the whats-cooking report.
I’ve posted the next version now.
And I’m sorry for not simply sending a message sometime in July that this topic was stalled. I was _not_ away from the computer for over a month, and I could have easily sent a quick message about the status.
v4 cover doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.
Here one change lead to another in order to make sure that everything stayed coherent. So here’s a linear overview of the changes (as of v4):
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain the “key” format, and add a new example
• Patch 8: join some existing paragraphs that are about the same theme since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in patch 5 later in the doc
• Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behavior
Thanks to everyone who has been reviewing these so far. I understand that these eleven changes are very incremental and piecemeal (see “very cross-referenced commit messages”). And the commit messages can be quite long, just to explain (again) very small changes. See for example patch “replace “lines” with “metadata”” in this version, where I explain why to write “trailer metadata” instead of “trailers metadata”. But right now I feel like prose sometimes needs all this ceremony. With code you get restraints like coding style, then you have all the years of looser rules about when to use certain data structures, when to make helper methods, etc. But with prose it seems that you bring much more of your individuality to it. That means more choices, and many of them are not obvious to the reader of the document, which means that you need to explain it in the commit message. Then you also have to consider the writing history of the document, and this one is twelve years old at this point; see the history review in commit message “join new-trailers again”, after the thematic break (***).
§ Changes in v4
See the patch Notes for details. Some minor things might not be mentioned here. But they are all mentioned on the patch Notes.
Patch “add key format example”: fix doubled “to”.
Patch “commit to “trailer block” term”: simplify “blank line” mention a little bit. But I might need some feedback from Junio on whether I interpreted his comment correctly. There are detailed notes on the patch.
Also follow up on other copy editing feedback from Junio.[1] Note the things that I didn’t follow up on because I disagreed or didn’t understand.
Patch “rewrite new-trailers paragraphs”: copy editing feedback from Junio.
Patch “replace “lines” with “metadata””: use “trailer metadata”. Suggested by Matt Hunter. It reads better.
Patch “document comment line treatment”: rewrite motivation for documenting how comment lines are treated.
🔗 1: https://lore.kernel.org/git/[email protected]/
§ Apologies for very cross-referenced commit messages
(see v3)
§ Cc
(see v2)
https://lore.kernel.org/git/[email protected]/
§ In-reply-to: v1
The recommendation to reply to the first version/cover letter is from topic ps/doc-recommend-b4, which is in next right now.
§ Link to v3
https://lore.kernel.org/git/[email protected]/
[01/11] doc: interpret-trailers: stop fixating on RFC 822 [02/11] doc: interpret-trailers: replace “lines” with “metadata” [03/11] doc: interpret-trailers: use “metadata” in Name as well [04/11] doc: interpret-trailers: not just for commit messages [05/11] doc: interpret-trailers: explain the format after the intro [06/11] doc: interpret-trailers: explain key format [07/11] doc: interpret-trailers: add key format example [08/11] doc: interpret-trailers: join new-trailers again [09/11] doc: interpret-trailers: commit to “trailer block” term [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs [11/11] doc: interpret-trailers: document comment line treatment
Documentation/git-interpret-trailers.adoc | 88 ++++++++++++++++------- 1 file changed, 64 insertions(+), 24 deletions(-)
Interdiff against v3:
Documentation/git-interpret-trailers.adoc +15 -15
@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse trailers metadata at the end of the otherwise +Add or parse trailer 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
@@ -66,14 +66,14 @@ Also by default, this new trailer will only be added if the last trailer is different to it. 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. +preceded by a blank line, so a blank line will be inserted before the +new trailer block in that case. -More concretely, this is how the new trailer is added: a `<key>=<value>` -or `<key>:<value>` argument given using `--trailer` will be appended -after the existing trailers. The _<key>_ and _<value>_ parts will be -trimmed to remove starting and trailing whitespace, and the resulting -trimmed _<key>_ and _<value>_ will appear in the output like this: +This is how the new trailer is added: a `<key>=<value>` or +`<key>:<value>` argument given using `--trailer` will be appended after +the existing trailers. The _<key>_ and _<value>_ parts will be trimmed +to remove starting and trailing whitespace, and the resulting trimmed +_<key>_ and _<value>_ will appear in the output like this: ------------------------------------------------ key: value
@@ -83,14 +83,14 @@ This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). 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) +trailer block. A trailer block 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 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). +The trailer block is by definition at the end of the commit message. +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). For convenience, a _<key-alias>_ can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the
@@ -419,8 +419,8 @@ 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. +* Here we try to use three different trailer keys. But it fails because + two of them are not recognized as trailer keys. + ---- $ cat msg.txt
Range-diff against v3:
1: e5d58237bc2 ! 1: 2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822
@@ Metadata
## Commit message ##
doc: interpret-trailers: stop fixating on RFC 822
- This command handles the trailers metadata format. But the command
+ This command handles the trailer metadata format. But the command
isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers.
2: 5ddd39bf157 ! 2: 859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata”
@@ Commit message
† 1: 68e3c69e (Documentation/glossary: describe "trailer", 2024-11-17)
+ Let’s not emphasize “trailer” here since we are going to define the term
+ in the upcoming commit “explain the format after the intro”.
+
+ Let’s call it “trailer metadata” rather than “trailers metadata”.
+ At first it seemed better to use the latter:
+
+ 1. We’re introducing the jargon, and the format is often discussed as
+ plural “trailers”, with its constituent parts being singular
+ “trailer”
+ 2. What this replaces uses “trailer”, but it rescues the plural mood
+ with “lines”
+ 3. This is very soon going to go into the constituent parts, including
+ each trailer, so we’re contrasting the concept name (trailers) with
+ its parts
+
+ But:
+
+ 1. The former reads better (most important)
+ 2. “Trailer *metadata*” suggests plurality, similar to “trailer *lines*”
+
+ Helped-by: Matt Hunter <[email protected]>
## Documentation/git-interpret-trailers.adoc ##
@@ Documentation/git-interpret-trailers.adoc: git interpret-trailers [--in-place] [
DESCRIPTION
-----------
-Add or parse _trailer_ lines at the end of the otherwise
-+Add or parse trailers metadata at the end of the otherwise
++Add or parse trailer metadata at the end of the otherwise
free-form part of a commit message. For example, in the following commit message
3: 9f0227a1978 ! 3: ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well
@@ Metadata
## Commit message ##
doc: interpret-trailers: use “metadata” in Name as well
- We now since the previous commit introduce the format as “trailers
+ We now since the previous commit introduce the format as “trailer
metadata”. We can replace “structured information” with “metadata” in the “Name” section to be consistent.
4: 4cb26810d4e ! 4: b79ddf3b13e doc: interpret-trailers: not just for commit messages
@@ Documentation/git-interpret-trailers.adoc
@@ Documentation/git-interpret-trailers.adoc: git interpret-trailers [--in-place] [--trim-empty]
DESCRIPTION
-----------
- Add or parse trailers metadata at the end of the otherwise
+ Add or parse trailer metadata at the end of the otherwise
-free-form part of a commit message. For example, in the following commit -message
+free-form part of a commit message, or any other kind of text.
5: 196c91bebe3 ! 5: e7101eb1fcb doc: interpret-trailers: explain the format after the intro
@@ Commit message
well as define the most important terms.
Note that we name the “blank line” rule since I want to use that term
- every time it comes up. It gets very mildly obfuscated if you call it a
- “blank line” in one place[2] and “empty (or whitespace-only) ...” in
+ every time it comes up. It gets very mildly obfuscated if you call it
+ a “blank line” in one place[2] and “empty (or whitespace-only) ...” in
another one.[3]
We will define the format of the *key* in the next commit.
@@ Commit message
## Documentation/git-interpret-trailers.adoc ##
@@ Documentation/git-interpret-trailers.adoc: DESCRIPTION
-----------
- Add or parse trailers metadata at the end of the otherwise
+ Add or parse trailer metadata at the end of the otherwise free-form part of a commit message, or any other kind of text. -For example, in the following commit message
+
6: 688ea55599a ! 6: 557b5b5564a doc: interpret-trailers: explain key format
@@ Commit message
## Documentation/git-interpret-trailers.adoc ##
-@@ Documentation/git-interpret-trailers.adoc: Add or parse trailers metadata at the end of the otherwise +@@ Documentation/git-interpret-trailers.adoc: Add or parse trailer 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
7: e6eafbd641f ! 7: eee81fc99fa doc: interpret-trailers: add key format example
@@ Documentation/git-interpret-trailers.adoc: 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.
++* Here we try to use three different trailer keys. But it fails because ++ two of them are not recognized as trailer keys.
++
+----
+$ cat msg.txt
8: 8849ace33e6 ! 8: cd3e47459c7 doc: interpret-trailers: join new-trailers again
@@ Metadata
## Commit message ##
doc: interpret-trailers: join new-trailers again
- There are three trailers that talk about how a new trailer is added.
+ There are three paragraphs that talk about how a new trailer is added.
But the first one is separated from the other two by two paragraphs about how key-alias can make using --trailer more convenient. This short how-to does not follow thematically from the previous paragraph,
9: 8323b84e134 ! 9: c50b6d25170 doc: interpret-trailers: commit to “trailer block” term
@@ Commit message
invented term.
That term was useful to explain where the trailers are found (they
- *trail* the message). But it is also useful here, where we explain how
- trailers are added to existing messages, how trailer blocks are
- found (beyond the simple case in the introduction), and how the end of
- the message is found.
+ *trail* the message). But it is also useful here, where we explain
+ how trailers are added to existing messages, how trailer blocks are
+ found (beyond the simple case in the introduction), and how the end
+ of the message is found.
+
+ Also note that we simplify the “blank line” point. The text says:
+
+ A blank line will be added before the new trailer if there isn't one
+ already.
+
+ But this isn’t quite coherent. The previous sentence says “If there is
+ no existing trailer”, so we are in one of these modes:
+
+ 1. discussing trailer blocks in general; or
+ 2. discussing creating a new trailer block in particular.
+
+ If (1), then we shouldn’t add a blank line before the new trailer if
+ there exists a trailer block already. And if (2), then the “if there
+ isn’t one already” is redundant.[2] So just talking about the higher-
+ level “trailer block” simplifies the text, since we don’t have to worry
+ about the different contexts that *trailers* can find themselves in.
† 1: in commit “explain the format after the intro”
+ † 2: Note that non-trailer lines don’t matter here; if you have a
+ trailer block consisting of (cherry picked from commit <commit>),
+ then you still shouldn’t insert a blank line before the new trailer
+ since that would create a new trailer block
@@ Documentation/git-interpret-trailers.adoc: key: value
+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. ++preceded by a blank line, so a blank line will be inserted before the ++new trailer block in that case.
+
+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) ++trailer block. A trailer block 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.
@@ Documentation/git-interpret-trailers.adoc: key: value
-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).
++The trailer block is by definition at the end of the commit message. ++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).
For convenience, a _<key-alias>_ can be configured to make using --trailer shorter to type on the command line. This can be configured using the
10: c7495c3b39e ! 10: c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs
@@ Commit message
1. Declare that we are about to talk about --trailer appending
2. Explain the default behavior
3. Explain how this affects the trailer block
- 4. Then state the same thing (“More concretely”) in concrete terms with
- placeholders
+ 4. Then discuss what each trailer line will look like
@@ Documentation/git-interpret-trailers.adoc: are applied to each input and the way
-using --trailer will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
--to remove starting and trailing whitespace, and the resulting trimmed --_<key>_ and _<value>_ will appear in the output like this:
+Let's consider new trailers added with --trailer.
+By default, the new trailer will appear at the end of the trailer block. +Also by default, this new trailer will only be added
+if the last trailer is different to it.
+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. ++preceded by a blank line, so a blank line will be inserted before the ++new trailer block in that case.
+
-+More concretely, this is how the new trailer is added: a <key>=<value> -+or <key>:<value> argument given using --trailer will be appended -+after the existing trailers. The _<key>_ and _<value>_ parts will be -+trimmed to remove starting and trailing whitespace, and the resulting -+trimmed _<key>_ and _<value>_ will appear in the output like this:
++This is how the new trailer is added: a <key>=<value> or ++<key>:<value> argument given using --trailer will be appended after ++the existing trailers. The _<key>_ and _<value>_ parts will be trimmed
+ to remove starting and trailing whitespace, and the resulting trimmed
+ _<key>_ and _<value>_ will appear in the output like this:
- ------------------------------------------------
- key: value
@@ Documentation/git-interpret-trailers.adoc: key: value
This means that the trimmed _<key>_ and _<value>_ will be separated by ":{nbsp}" (one colon followed by one space).
@@ Documentation/git-interpret-trailers.adoc: key: value
-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.
+-preceded by a blank line, so a blank line will be inserted before the +-new trailer block in that case.
-
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)
+ trailer block. A trailer block is a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or
11: fc38e8660f0 ! 11: 7d20cb7528f doc: interpret-trailers: document comment line treatment
@@ Commit message
Comment lines have always been ignored but this is not documented.
- This is mostly for completeness since this is unlikely to catch anyone
- by surprise. But we really ought to be reasonably complete here since
- it’s the only documentation page that documents trailers.
+ The primary motivation here is to reasonably complete in the
+ documentation of how trailers are parsed; this is after all the only
+ documentation page that documents this format. However, and going beyond
+ that point, we could imagine that someone would want to use this format
+ outside a commit (or tag) message context, like say in Git notes.
+
+ On the other hand, it seems far-fetched that someone would be caught
+ off guard by this considering that comment characters/strings are not
+ likely to be alphanumeric,[1] which would mean that these comment lines
+ would be treated as non-trailer lines if they were *not* detected and
+ removed as comment lines.
+
+ † 1: A notable exception is that Jujutsu VCS uses JJ: as
+ the comment string
base-commit: 5361983c075154725be47b65cca9a2421789e410
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 1/11 doc: interpret-trailers: stop fixating on RFC 822
From: Kristoffer Haugsbakk <[email protected]>
This command handles the trailer metadata format. But the command isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers.
This is overwrought; most people do not deal directly with email headers, and certainly not email RFCs.
Trailers are just key–value pairs that, like email headers, use colon as the separator. The format in its simplest form is easy to describe directly without comparing it to anything else; we will do that in the upcoming commit “explain the format after the intro”.
For now, let’s:
• remove the first mention of email headers;
• keep the second, innocuous comparison with email line folding in the middle; and
• remove the now-unneeded disclaimer that trailers do not share many of the features of RFC 822 email headers—there is no invitation to speculate that trailers would follow any other email format rules since we do not compare them directly any more.
***
Talking about trailers as an RFC 822/2822-like format seems to go back to the --fixes/Fixes: trailer topic,[1] the thread that precipitated this command and in turn the first trailer support in git(1) beyond adding s-o-b lines.
† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/
---
Notes (series):
v4:
• Msg: s/trailers metadata/trailer metadata/ (knock-on effect from change in the *next* commit)
---
v2:
• Use *** as a thematic break instead of ❦
• Change to “metadata” instead of “key–value pairs” since this series version adds a paragraph after this one where we dig into this term. And “metadata” describes the purpose of this format.
Documentation/git-interpret-trailers.adoc | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +3 -6
@@ -14,9 +14,9 @@ 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 _trailer_ lines at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject
@@ -107,9 +107,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`::
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 2/11 doc: interpret-trailers: replace “lines” with “metadata”
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We removed the initial comparison to email headers in the previous commit. Now the introduction paragraph just says “trailer lines”, and the only hint that this is metadata/structured information is the “otherwise free-form” phrase.
Let’s replace “lines” with “metadata” since that is their purpose. This also makes the introduction more consistent with how I chose to define trailers in the glossary:[1] “Key-value metadata”. (We will introduce “key–value” in the upcoming commit “explain the format after the intro”.)
† 1: 68e3c69e (Documentation/glossary: describe "trailer", 2024-11-17)
Let’s not emphasize “trailer” here since we are going to define the term in the upcoming commit “explain the format after the intro”.
Let’s call it “trailer metadata” rather than “trailers metadata”. At first it seemed better to use the latter:
1. We’re introducing the jargon, and the format is often discussed as plural “trailers”, with its constituent parts being singular “trailer”
2. What this replaces uses “trailer”, but it rescues the plural mood with “lines”
3. This is very soon going to go into the constituent parts, including each trailer, so we’re contrasting the concept name (trailers) with its parts
But:
1. The former reads better (most important)
2. “Trailer *metadata*” suggests plurality, similar to “trailer *lines*”
---
Notes (series):
v4:
• s/trailers metadata/trailer metadata/ since it reads better (and see commit message for details)
🔗 https://lore.kernel.org/git/[email protected]/
• Msg: Add a paragraph to explain why we remove the emphasis from “trailer”. In the previous version we replaced “trailer” with “trailers”, so we didn’t need to explain it then.
---
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailer metadata at the end of the otherwise free-form part of a commit message. For example, in the following commit message
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 3/11 doc: interpret-trailers: use “metadata” in Name as well
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We now since the previous commit introduce the format as “trailer metadata”. We can replace “structured information” with “metadata” in the “Name” section to be consistent.
While “structured information” does emphasize that the data is not loosely structured, we also say that this command adds to or parses this format. I don’t think that we need to emphasize that it is structured since clearly there is some structure there.
Both “metadata” and “structured information” can convey the same information. But “metadata” is shorter and easier to deploy since it’s just one word.
---
Notes (series):
v4:
• Msg: s/trailers metadata/trailer metadata/ (knock-on effect from
change in the prevoius commit)
---
v2: [new]Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -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 --------
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 4/11 doc: interpret-trailers: not just for commit messages
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
This command doesn’t interface with commits directly. You can interpret or modify any kind of text, even though commit messages are the most relevant.
The git(1) suite also isn’t restricted to only direct commit support since git-tag(1) learned --trailer in 066cef77 (builtin/tag: add --trailer option, 2024-05-05)
Now, we already introduce the command in the “Name” section as dealing with commit messages as well. That is fine since that intro line needs to remain pretty short.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.adoc +2 -2
@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- Add or parse trailer metadata at the end of the otherwise -free-form part of a commit message. For example, in the following commit -message +free-form part of a commit message, or any other kind of text. +For example, in the following commit message ------------------------------------------------ subject
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 5/11 doc: interpret-trailers: explain the format after the intro
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
You need to read the entire “Description” section in order to understand the full trailer format. But there are many nuances, so that’s fine. As a starter though we have an introductory example.[1] That turns out to be crucial; the rest of this section talks about the mechanics of the command and only incidentally the format itself.
Now, although the example might arguably be self-explanatory, we can add a little preamble which defines the format in its simplest form as well as define the most important terms.
Note that we name the “blank line” rule since I want to use that term every time it comes up. It gets very mildly obfuscated if you call it a “blank line” in one place[2] and “empty (or whitespace-only) ...” in another one.[3]
We will define the format of the *key* in the next commit.
† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,
2023-06-15)
† 2: `Documentation/git-interpret-trailers.adoc:86` in
5361983c (The 22nd batch, 2026-03-27)
† 3: `Documentation/git-interpret-trailers.adoc:93` in
5361983c (The 22nd batch, 2026-03-27)---
Notes (series):
v4: Msg: reflow paragraph
v2: [new]
• PS: Suggested here: https://lore.kernel.org/git/[email protected]/#t
• (My tardiness on this topic has made these reminders necessary,
if only for my own reference)
Documentation/git-interpret-trailers.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +6 -1
@@ -16,7 +16,12 @@ DESCRIPTION ----------- Add or parse trailer metadata at the end of the otherwise free-form part of a commit message, or any other kind of text. -For example, in the following commit message + +A _trailer_ in its simplest form is a key-value pair with a colon as a +separator. 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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 6/11 doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and only basing their trailer keys on the documentation examples.[1]
The previous commit provided us with an appropriate paragraph to describe the key format.
† 1: Technically they would then miss out on using digits in them since
all of the example keys just use letters and hyphens
---
Notes (series):
v2:
• PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/
• Remove the “paint by numbers” reference after review (unclear)
• Add apropos footnote
• Tweak the paragraph about how we now have a context to describe
this format
v1: [had a note about code spelunking (isalnum(3))]
Documentation/git-interpret-trailers.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +2 -1
@@ -18,7 +18,8 @@ Add or parse trailer 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. A _trailer block_ consists of one or more trailers. The +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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 7/11 doc: interpret-trailers: add key format example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
All of the examples speak of the Happy Path where everything works as intended. But failure examples can also be instructive. Especially for explaining again, by example, the key format (see previous commit).
This also allows us to demonstrate trailer block detection with a concrete example.
---
Notes (series):
v4: Fix doubled word “to to”
v2: [new]
Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
Documentation/git-interpret-trailers.adoc +23 -0
@@ -405,6 +405,29 @@ mv "\$1.new" "\$1" $ chmod +x .git/hooks/commit-msg ------------ +* Here we try 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 <[email protected]> +$ 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]
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 8/11 doc: interpret-trailers: join new-trailers again
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
There are three paragraphs that talk about how a new trailer is added. But the first one is separated from the other two by two paragraphs about how key-alias can make using --trailer more convenient. This short how-to does not follow thematically from the previous paragraph, and can wait until we have fully described how a new trailer is added. So let’s move the three paragraphs about the new-trailer topic together and move the how-to paragraphs after that.
***
Let’s now review the history of the document. Even if the document is not quite correct in its current state, just doing the apparently obvious edit without considering the history does not respect the effort that went into changing the document in the past.
These three paragraphs were originally next to each other, in the first version of the doc.[1] But extra sentences about this how-to topic was added to the first paragraph nine years later:[2]
[...]
': ' (one colon followed by one space). For convenience, the <token> can be a shortened string key (e.g., "sign") instead of the full string which should [...]
And then it was split into it’s own paragraph a little later.[3]
This evolution shows, in my opinion, that this how-to never followed thematically from the existing topic. Which means that there is nothing that was potentially lost to time that we need to restore or respect.
† 1: dfd66ddf (Documentation: add documentation for 'git
interpret-trailers', 2014-10-13)
† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)
† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
2023-09-07)---
Notes (series):
v4:
• Msg: Fix word-confusion: s/There are three trailers/There are three paragraphs.
🔗 https://lore.kernel.org/git/CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com/
I knew that I was going to fix this when I started on version 4. But you would not believe how many times I went over the commit log without seeing that I had neglected to do this part.
---
v3: [new]
• Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/
• Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-)
Documentation/git-interpret-trailers.adoc +13 -13
@@ -74,19 +74,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -For convenience, a _<key-alias>_ can be configured to make using `--trailer` -shorter to type on the command line. This can be configured using the -`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix -of the full _<key>_ string, although case sensitivity does not matter. For -example, if you have - ------------------------------------------------- -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
@@ -101,6 +88,19 @@ 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). +For convenience, a _<key-alias>_ can be configured to make using `--trailer` +shorter to type on the command line. This can be configured using the +`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix +of the full _<key>_ string, although case sensitivity does not matter. For +example, if you have + +------------------------------------------------ +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"`. + When reading trailers, there can be no whitespace before or inside the _<key>_, but any number of regular space and tab characters are allowed between the _<key>_ and the separator. There can be whitespaces before,
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 9/11 doc: interpret-trailers: commit to “trailer block” term
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We chose to introduce the term “trailer block” into the documentation a few commits ago.[1] It is used in the code though, so it is not a newly invented term.
That term was useful to explain where the trailers are found (they *trail* the message). But it is also useful here, where we explain how trailers are added to existing messages, how trailer blocks are found (beyond the simple case in the introduction), and how the end of the message is found.
Also note that we simplify the “blank line” point. The text says:
A blank line will be added before the new trailer if there isn't one already.
But this isn’t quite coherent. The previous sentence says “If there is no existing trailer”, so we are in one of these modes:
1. discussing trailer blocks in general; or
2. discussing creating a new trailer block in particular.
If (1), then we shouldn’t add a blank line before the new trailer if there exists a trailer block already. And if (2), then the “if there isn’t one already” is redundant.[2] So just talking about the higher- level “trailer block” simplifies the text, since we don’t have to worry about the different contexts that *trailers* can find themselves in.
† 1: in commit “explain the format after the intro”
† 2: Note that non-trailer lines don’t matter here; if you have a
trailer block consisting of (cherry picked from commit <commit>), then you still shouldn’t insert a blank line before the new trailer since that would create a new trailer block
---
Notes (series):
v4:
• Tweak “blank line” reminder (“Recall that”) by dropping “specifically” since it is redundant based on [1]. Well, I thought I understood the feedback here but reading it again today I was confused. @Junio, did I understand it correctly?
My thought process: This “recall that” is similar to other “recall” phrases added in the series. They add some redundancy, similar in spirit to 74522b6b (Documentation/git-update-ref.txt:
discuss symbolic refs, 2024-10-21) :
| Add a paragraph which just emphasizes that the command without | any options does not support refs in the final arguments. This | is clear already from the names <new-oid> and <old-oid> but | the right balance of redundancy makes documentation robust | against stray interpretation.
• Msg: Editing the above I noticed that the previous (before this change “blank line” explanation isn’t (quite) coherent. I want to explain every meaningful point of change in the commit message, so I dedicate some “also” paragraphs to that change.
• For [1] again: s/Concretely, that/A trailer block/ since it flows better
• For [1] again: Fix mangled “The trailer block is by definition” sentence and make sure to use “commit message”. We use “commit message” throughout the doc, not just “message”. But just use “message” in the next sentence since it is clear that we are still talking about *commit* message.
• Msg: Reflow existing paragraph
🔗 1: https://lore.kernel.org/git/[email protected]/#t
---
v2: [new]
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-)
Documentation/git-interpret-trailers.adoc +14 -12
@@ -74,19 +74,21 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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. - -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 +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 will be inserted before the +new trailer block in that case. + +Existing trailers are extracted from the input by looking for the +trailer block. A trailer block 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 of the commit message. +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). For convenience, a _<key-alias>_ can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 10/11 doc: interpret-trailers: rewrite new-trailers paragraphs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Two commits ago we moved new-trailers paragraph next to each other. But there is something curious about two of them:
By default the new trailer will appear at the end of the trailer block. [...]
Then a source block and a paragraph later:
By default, a <key>=<value> or <key>:<value> argument given using --trailer will be appended after the existing trailers only if [...]
Why are there two paragraphs that talk about how “By default” a trailer will be appended?
We can make these paragraphs flow better, and with a more distinct character each, by dividing the flow like this:
1. Declare that we are about to talk about --trailer appending
2. Explain the default behavior
3. Explain how this affects the trailer block
4. Then discuss what each trailer line will look like
---
Notes (series):
v4:
• Simplify “This is how the new trailer” paragraph: drop “More concretely,” since it is misleading (this is not a “more concretely continuation of the preceding paragraph(s))[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
---
v3: [new]
• Based on draft: https://lore.kernel.org/git/[email protected]/
• See msg:
Two commits ago we moved new-trailers paragraph next to each other.
This commit here might fit better one step back. So that it becomes the commit right after. But I can deal with that commit movement if this change is accepted. For now I didn’t bother.
Documentation/git-interpret-trailers.adoc | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-)
Documentation/git-interpret-trailers.adoc +12 -10
@@ -60,10 +60,18 @@ are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers. -By default, a `<key>=<value>` or `<key>:<value>` argument given -using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed +Let's consider new trailers added with `--trailer`. +By default, the new trailer will appear at the end of the trailer block. +Also by default, this new trailer will only be added +if the last trailer is different to it. +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 will be inserted before the +new trailer block in that case. + +This is how the new trailer is added: a `<key>=<value>` or +`<key>:<value>` argument given using `--trailer` will be appended after +the existing trailers. The _<key>_ and _<value>_ parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed _<key>_ and _<value>_ will appear in the output like this:
@@ -74,12 +82,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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 will be inserted before the -new trailer block in that case. - Existing trailers are extracted from the input by looking for the trailer block. A trailer block is a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v4 11/11 doc: interpret-trailers: document comment line treatment
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Comment lines have always been ignored but this is not documented.
The primary motivation here is to reasonably complete in the documentation of how trailers are parsed; this is after all the only documentation page that documents this format. However, and going beyond that point, we could imagine that someone would want to use this format outside a commit (or tag) message context, like say in Git notes.
On the other hand, it seems far-fetched that someone would be caught off guard by this considering that comment characters/strings are not likely to be alphanumeric,[1] which would mean that these comment lines would be treated as non-trailer lines if they were *not* detected and removed as comment lines.
† 1: A notable exception is that Jujutsu VCS uses JJ: as
the comment string
---
Notes (series):
v4:
• Msg: rewrite motivation for documenting this. The motivation is not super solid, but it reflects my own ambiguity on the matter, so to speak; I think we ought to be very thorough about documenting the format, while making sure to not use the main text to exhaustively lay it all out. The information should be somewhere in this doc. But not in your face.
• Msg: Add “(or tag) message”. See patch “not just for commit messages” where trailer support for tag messages are mentioned.
---
v3:
• Msg: finally fix area
• Demote this point to its own “other rules” section, out of the main running text. It is not important enough for the main text.
• Since writing this I have realized that we can go into that long
# ----- >8 ----
Commit message separator scissor line, maybe other things. But I stop short here. These things are even less likely to become a problem for anyone. And maybe we’ll add them later?
v2: [new]
Documentation/git-interpret-trailers.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+)
Documentation/git-interpret-trailers.adoc +10 -0
@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and newlines in it. ------------------------------------------------ +OTHER RULES +----------- + +What was covered in the previous section are the rules that are relevant +for regular use. The following points are included for completeness. + +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. + OPTIONS ------- `--in-place`::
Signature · 1 line
2.54.0.22.g9e26862b904
Re: [PATCH v4 11/11] doc: interpret-trailers: document comment line treatment
Hi Kristoffer,
Quoted 6 lines · On Thu, Jul 30, 2026 at 5:22 AM <[email protected]> wrote:
From: Kristoffer Haugsbakk <[email protected]>
Comment lines have always been ignored but this is not documented.
The primary motivation here is to reasonably complete in the
"to be"?
Quoted 17 lines
documentation of how trailers are parsed; this is after all the only documentation page that documents this format. However, and going beyond that point, we could imagine that someone would want to use this format outside a commit (or tag) message context, like say in Git notes.
On the other hand, it seems far-fetched that someone would be caught off guard by this considering that comment characters/strings are not likely to be alphanumeric,[1] which would mean that these comment lines would be treated as non-trailer lines if they were *not* detected and removed as comment lines.
† 1: A notable exception is that Jujutsu VCS uses
JJ:as
the comment stringSigned-off-by Kristoffer Haugsbakk <[email protected]>---
Quoted 8 lines
Notes (series):
v4:
• Msg: rewrite motivation for documenting this. The motivation is not super solid, but it reflects my own ambiguity on the matter, so to speak; I think we ought to be very thorough about documenting the format, while making sure to not use the main text to exhaustively lay it all out. The information should be somewhere in this doc. But not in your face.
I agree we should be thorough but not in your face, esp. based on the work Julia Evans has done in the past around Git documentation. Thanks!
Quoted 3 lines
• Msg: Add “(or tag) message”. See patch “not just for commit messages” where trailer support for tag messages are mentioned.
[snip]
Signature · 1 line
D. Ben Knoble
Re: [PATCH v4 11/11] doc: interpret-trailers: document comment line treatment
Quoted 11 lines · D. Ben Knoble
Hi Kristoffer,
Quoted 6 lines · On Thu, Jul 30, 2026 at 5:22 AM <[email protected]> wrote:
From: Kristoffer Haugsbakk <[email protected]>
Comment lines have always been ignored but this is not documented.
The primary motivation here is to reasonably complete in the
"to be"?
Thanks. I keep staring at the text but in the end you need someone else to read it as well.
Quoted 10 lines
Quoted 9 lines
[snip]
Notes (series):
v4:
• Msg: rewrite motivation for documenting this. The motivation is not super solid, but it reflects my own ambiguity on the matter, so to speak; I think we ought to be very thorough about documenting the format, while making sure to not use the main text to exhaustively lay it all out. The information should be somewhere in this doc. But not in your face.
Quoted 3 lines
I agree we should be thorough but not in your face, esp. based on the work Julia Evans has done in the past around Git documentation. Thanks!
Thanks. I’m glad that I was able to communicate that. ;)
Quoted 2 lines
Quoted 2 lines
[snip]
Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format
In reply to [email protected]Hi Kristoffer,
Apologies for not returning to this for a while! I haven't read the whole v4 in detail, but I reviewed the final diff and output.
Quoted 10 lines · On Thu, Jul 30, 2026 at 5:18 AM <[email protected]> wrote:
From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.
Quoted 5 lines
Here one change lead to another in order to make sure that everything stayed coherent. So here’s a linear overview of the changes (as of v4):
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
One small comment on patch 4
Quoted 8 lines
• Patches 5–7: Explain the format in the simplest case, explain the “key” format, and add a new example
• Patch 8: join some existing paragraphs that are about the same theme since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in patch 5 later in the doc
• Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behavior
A few places we use an inline list syntax ("… (i) stuff … (ii) more stuff …"). In the added example about ASCII trailers it is useful because we make reference to (ii); in the initial part of the manual, I don't see any references to the delimited items, so I'm not sure if it's worth numbering them.
Not a strong statement, though, so I'm happy either way. Everything else (that I looked at, see above) looks good to me.
Thanks!
Signature · 1 line
D. Ben Knoble
Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format
Quoted 10 lines · D. Ben Knoble
One small comment on patch 4
...
A few places we use an inline list syntax ("… (i) stuff … (ii) more stuff …"). In the added example about ASCII trailers it is useful because we make reference to (ii); in the initial part of the manual, I don't see any references to the delimited items, so I'm not sure if it's worth numbering them.Not a strong statement, though, so I'm happy either way. Everything else (that I looked at, see above) looks good to me.
I guess we are gettng very close to the finish line. Kristoffer, how would we want to proceed?
Thanks, both.
Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format
Quoted 10 lines · Junio C Hamano
Quoted 8 lines · D. Ben Knoble
One small comment on patch 4
...
A few places we use an inline list syntax ("… (i) stuff … (ii) more stuff …"). In the added example about ASCII trailers it is useful because we make reference to (ii); in the initial part of the manual, I don't see any references to the delimited items, so I'm not sure if it's worth numbering them.
Quoted 7 lines
Quoted 2 lines
Not a strong statement, though, so I'm happy either way. Everything else (that I looked at, see above) looks good to me.
I guess we are gettng very close to the finish line. Kristoffer, how would we want to proceed?
Thanks, both.
I will wait at least one day for any more comments and post a new version with that fix that Knoble found to the commit message.
Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format
In reply to D. Ben KnobleQuoted 4 lines · D. Ben Knoble
Hi Kristoffer,
Apologies for not returning to this for a while! I haven't read the whole v4 in detail, but I reviewed the final diff and output.
Your reviews, in whatever timeframe, are very much appreciated.
Quoted 8 lines · On Thu, Jul 30, 2026 at 5:18 AM <[email protected]> wrote:
Quoted 1 line
[snip]
A few places we use an inline list syntax ("… (i) stuff … (ii) more stuff …"). In the added example about ASCII trailers it is useful because we make reference to (ii); in the initial part of the manual, I don't see any references to the delimited items, so I'm not sure if it's worth numbering them.
I did adopt that Roman numeral inline list style for the example based on the existing one.
I’ve always read it as a stylistic choice. So not for the ability to reference them. You have that ability, but I have the impression that most inline lists like that are not used to reference back to the item.
This existing inline list goes back long before this series. Changing it would mean adding another change to an already long series. And I’m not sure that it should be changed in the first place. So for now at least I am not going to pick up on this topic.
I will wait at least a day for any more comments and post a new version with that fix to the commit message.
Quoted 2 lines
[snip]
v5 cover doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.
Here one change lead to another in order to make sure that everything stayed coherent. So here’s a linear overview of the changes (as of v4):
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain the “key” format, and add a new example
• Patch 8: join some existing paragraphs that are about the same theme since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in patch 5 later in the doc
• Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behavior
Thanks to everyone who has been reviewing these so far. I understand that these eleven changes are very incremental and piecemeal (see “very cross-referenced commit messages”). And the commit messages can be quite long, just to explain (again) very small changes. See for example patch “replace “lines” with “metadata”” in this version, where I explain why to write “trailer metadata” instead of “trailers metadata”. But right now I feel like prose sometimes needs all this ceremony. With code you get restraints like coding style, then you have all the years of looser rules about when to use certain data structures, when to make helper methods, etc. But with prose it seems that you bring much more of your individuality to it. That means more choices, and many of them are not obvious to the reader of the document, which means that you need to explain it in the commit message. Then you also have to consider the writing history of the document, and this one is twelve years old at this point; see the history review in commit message “join new-trailers again”, after the thematic break (***).
§ Changes in v5
Patch “document comment line treatment”: commit message: add missing word:
s/to/to be/.
§ Apologies for very cross-referenced commit messages
(see v3)
§ Cc
(see v2)
https://lore.kernel.org/git/[email protected]/
I have also added a new email since the email [email protected] bounces for me. There is a Brendan Jackman who has posted messages under a Gmail address. Hopefully it’s the same person.
§ In-reply-to: v1
The recommendation to reply to the first version/cover letter is from topic ps/doc-recommend-b4, which is in next right now.
§ Link to v4
https://lore.kernel.org/git/[email protected]/
[01/11] doc: interpret-trailers: stop fixating on RFC 822 [02/11] doc: interpret-trailers: replace “lines” with “metadata” [03/11] doc: interpret-trailers: use “metadata” in Name as well [04/11] doc: interpret-trailers: not just for commit messages [05/11] doc: interpret-trailers: explain the format after the intro [06/11] doc: interpret-trailers: explain key format [07/11] doc: interpret-trailers: add key format example [08/11] doc: interpret-trailers: join new-trailers again [09/11] doc: interpret-trailers: commit to “trailer block” term [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs [11/11] doc: interpret-trailers: document comment line treatment
Documentation/git-interpret-trailers.adoc | 88 ++++++++++++++++------- 1 file changed, 64 insertions(+), 24 deletions(-)
Interdiff against v4:
Range-diff against v4:
1: 2419b1a6863 = 1: 2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822 2: 859ab42ac41 = 2: 859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata” 3: ab5b4af970e = 3: ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well 4: b79ddf3b13e = 4: b79ddf3b13e doc: interpret-trailers: not just for commit messages 5: e7101eb1fcb = 5: e7101eb1fcb doc: interpret-trailers: explain the format after the intro 6: 557b5b5564a = 6: 557b5b5564a doc: interpret-trailers: explain key format 7: eee81fc99fa = 7: eee81fc99fa doc: interpret-trailers: add key format example 8: cd3e47459c7 = 8: cd3e47459c7 doc: interpret-trailers: join new-trailers again 9: c50b6d25170 = 9: c50b6d25170 doc: interpret-trailers: commit to “trailer block” term 10: c11a116605e = 10: c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs 11: 7d20cb7528f ! 11: cabbb05a1c4 doc: interpret-trailers: document comment line treatment
@@ Commit message
Comment lines have always been ignored but this is not documented.
- The primary motivation here is to reasonably complete in the
+ The primary motivation here is to be reasonably complete in the
documentation of how trailers are parsed; this is after all the only documentation page that documents this format. However, and going beyond that point, we could imagine that someone would want to use this format
base-commit: 5361983c075154725be47b65cca9a2421789e410
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 1/11 doc: interpret-trailers: stop fixating on RFC 822
From: Kristoffer Haugsbakk <[email protected]>
This command handles the trailer metadata format. But the command isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers.
This is overwrought; most people do not deal directly with email headers, and certainly not email RFCs.
Trailers are just key–value pairs that, like email headers, use colon as the separator. The format in its simplest form is easy to describe directly without comparing it to anything else; we will do that in the upcoming commit “explain the format after the intro”.
For now, let’s:
• remove the first mention of email headers;
• keep the second, innocuous comparison with email line folding in the middle; and
• remove the now-unneeded disclaimer that trailers do not share many of the features of RFC 822 email headers—there is no invitation to speculate that trailers would follow any other email format rules since we do not compare them directly any more.
***
Talking about trailers as an RFC 822/2822-like format seems to go back to the --fixes/Fixes: trailer topic,[1] the thread that precipitated this command and in turn the first trailer support in git(1) beyond adding s-o-b lines.
† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/
---
Notes (series):
v4:
• Msg: s/trailers metadata/trailer metadata/ (knock-on effect from change in the *next* commit)
---
v2:
• Use *** as a thematic break instead of ❦
• Change to “metadata” instead of “key–value pairs” since this series version adds a paragraph after this one where we dig into this term. And “metadata” describes the purpose of this format.
Documentation/git-interpret-trailers.adoc | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +3 -6
@@ -14,9 +14,9 @@ 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 _trailer_ lines at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject
@@ -107,9 +107,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`::
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 2/11 doc: interpret-trailers: replace “lines” with “metadata”
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We removed the initial comparison to email headers in the previous commit. Now the introduction paragraph just says “trailer lines”, and the only hint that this is metadata/structured information is the “otherwise free-form” phrase.
Let’s replace “lines” with “metadata” since that is their purpose. This also makes the introduction more consistent with how I chose to define trailers in the glossary:[1] “Key-value metadata”. (We will introduce “key–value” in the upcoming commit “explain the format after the intro”.)
† 1: 68e3c69e (Documentation/glossary: describe "trailer", 2024-11-17)
Let’s not emphasize “trailer” here since we are going to define the term in the upcoming commit “explain the format after the intro”.
Let’s call it “trailer metadata” rather than “trailers metadata”. At first it seemed better to use the latter:
1. We’re introducing the jargon, and the format is often discussed as plural “trailers”, with its constituent parts being singular “trailer”
2. What this replaces uses “trailer”, but it rescues the plural mood with “lines”
3. This is very soon going to go into the constituent parts, including each trailer, so we’re contrasting the concept name (trailers) with its parts
But:
1. The former reads better (most important)
2. “Trailer *metadata*” suggests plurality, similar to “trailer *lines*”
---
Notes (series):
v4:
• s/trailers metadata/trailer metadata/ since it reads better (and see commit message for details)
🔗 https://lore.kernel.org/git/[email protected]/
• Msg: Add a paragraph to explain why we remove the emphasis from “trailer”. In the previous version we replaced “trailer” with “trailers”, so we didn’t need to explain it then.
---
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines at the end of the otherwise +Add or parse trailer metadata at the end of the otherwise free-form part of a commit message. For example, in the following commit message
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 3/11 doc: interpret-trailers: use “metadata” in Name as well
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We now since the previous commit introduce the format as “trailer metadata”. We can replace “structured information” with “metadata” in the “Name” section to be consistent.
While “structured information” does emphasize that the data is not loosely structured, we also say that this command adds to or parses this format. I don’t think that we need to emphasize that it is structured since clearly there is some structure there.
Both “metadata” and “structured information” can convey the same information. But “metadata” is shorter and easier to deploy since it’s just one word.
---
Notes (series):
v4:
• Msg: s/trailers metadata/trailer metadata/ (knock-on effect from
change in the prevoius commit)
---
v2: [new]Documentation/git-interpret-trailers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +1 -1
@@ -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 --------
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 4/11 doc: interpret-trailers: not just for commit messages
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
This command doesn’t interface with commits directly. You can interpret or modify any kind of text, even though commit messages are the most relevant.
The git(1) suite also isn’t restricted to only direct commit support since git-tag(1) learned --trailer in 066cef77 (builtin/tag: add --trailer option, 2024-05-05)
Now, we already introduce the command in the “Name” section as dealing with commit messages as well. That is fine since that intro line needs to remain pretty short.
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.adoc +2 -2
@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- Add or parse trailer metadata at the end of the otherwise -free-form part of a commit message. For example, in the following commit -message +free-form part of a commit message, or any other kind of text. +For example, in the following commit message ------------------------------------------------ subject
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 5/11 doc: interpret-trailers: explain the format after the intro
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
You need to read the entire “Description” section in order to understand the full trailer format. But there are many nuances, so that’s fine. As a starter though we have an introductory example.[1] That turns out to be crucial; the rest of this section talks about the mechanics of the command and only incidentally the format itself.
Now, although the example might arguably be self-explanatory, we can add a little preamble which defines the format in its simplest form as well as define the most important terms.
Note that we name the “blank line” rule since I want to use that term every time it comes up. It gets very mildly obfuscated if you call it a “blank line” in one place[2] and “empty (or whitespace-only) ...” in another one.[3]
We will define the format of the *key* in the next commit.
† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,
2023-06-15)
† 2: `Documentation/git-interpret-trailers.adoc:86` in
5361983c (The 22nd batch, 2026-03-27)
† 3: `Documentation/git-interpret-trailers.adoc:93` in
5361983c (The 22nd batch, 2026-03-27)---
Notes (series):
v4: Msg: reflow paragraph
v2: [new]
• PS: Suggested here: https://lore.kernel.org/git/[email protected]/#t
• (My tardiness on this topic has made these reminders necessary,
if only for my own reference)
Documentation/git-interpret-trailers.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +6 -1
@@ -16,7 +16,12 @@ DESCRIPTION ----------- Add or parse trailer metadata at the end of the otherwise free-form part of a commit message, or any other kind of text. -For example, in the following commit message + +A _trailer_ in its simplest form is a key-value pair with a colon as a +separator. 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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 6/11 doc: interpret-trailers: explain key format
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and only basing their trailer keys on the documentation examples.[1]
The previous commit provided us with an appropriate paragraph to describe the key format.
† 1: Technically they would then miss out on using digits in them since
all of the example keys just use letters and hyphens
---
Notes (series):
v2:
• PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/
• Remove the “paint by numbers” reference after review (unclear)
• Add apropos footnote
• Tweak the paragraph about how we now have a context to describe
this format
v1: [had a note about code spelunking (isalnum(3))]
Documentation/git-interpret-trailers.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.adoc +2 -1
@@ -18,7 +18,8 @@ Add or parse trailer 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. A _trailer block_ consists of one or more trailers. The +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
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 7/11 doc: interpret-trailers: add key format example
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
All of the examples speak of the Happy Path where everything works as intended. But failure examples can also be instructive. Especially for explaining again, by example, the key format (see previous commit).
This also allows us to demonstrate trailer block detection with a concrete example.
---
Notes (series):
v4: Fix doubled word “to to”
v2: [new]
Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
Documentation/git-interpret-trailers.adoc +23 -0
@@ -405,6 +405,29 @@ mv "\$1.new" "\$1" $ chmod +x .git/hooks/commit-msg ------------ +* Here we try 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 <[email protected]> +$ 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]
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 8/11 doc: interpret-trailers: join new-trailers again
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
There are three paragraphs that talk about how a new trailer is added. But the first one is separated from the other two by two paragraphs about how key-alias can make using --trailer more convenient. This short how-to does not follow thematically from the previous paragraph, and can wait until we have fully described how a new trailer is added. So let’s move the three paragraphs about the new-trailer topic together and move the how-to paragraphs after that.
***
Let’s now review the history of the document. Even if the document is not quite correct in its current state, just doing the apparently obvious edit without considering the history does not respect the effort that went into changing the document in the past.
These three paragraphs were originally next to each other, in the first version of the doc.[1] But extra sentences about this how-to topic was added to the first paragraph nine years later:[2]
[...]
': ' (one colon followed by one space). For convenience, the <token> can be a shortened string key (e.g., "sign") instead of the full string which should [...]
And then it was split into it’s own paragraph a little later.[3]
This evolution shows, in my opinion, that this how-to never followed thematically from the existing topic. Which means that there is nothing that was potentially lost to time that we need to restore or respect.
† 1: dfd66ddf (Documentation: add documentation for 'git
interpret-trailers', 2014-10-13)
† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)
† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
2023-09-07)---
Notes (series):
v4:
• Msg: Fix word-confusion: s/There are three trailers/There are three paragraphs.
🔗 https://lore.kernel.org/git/CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com/
I knew that I was going to fix this when I started on version 4. But you would not believe how many times I went over the commit log without seeing that I had neglected to do this part.
---
v3: [new]
• Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/
• Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-)
Documentation/git-interpret-trailers.adoc +13 -13
@@ -74,19 +74,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -For convenience, a _<key-alias>_ can be configured to make using `--trailer` -shorter to type on the command line. This can be configured using the -`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix -of the full _<key>_ string, although case sensitivity does not matter. For -example, if you have - ------------------------------------------------- -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
@@ -101,6 +88,19 @@ 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). +For convenience, a _<key-alias>_ can be configured to make using `--trailer` +shorter to type on the command line. This can be configured using the +`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix +of the full _<key>_ string, although case sensitivity does not matter. For +example, if you have + +------------------------------------------------ +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"`. + When reading trailers, there can be no whitespace before or inside the _<key>_, but any number of regular space and tab characters are allowed between the _<key>_ and the separator. There can be whitespaces before,
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 9/11 doc: interpret-trailers: commit to “trailer block” term
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
We chose to introduce the term “trailer block” into the documentation a few commits ago.[1] It is used in the code though, so it is not a newly invented term.
That term was useful to explain where the trailers are found (they *trail* the message). But it is also useful here, where we explain how trailers are added to existing messages, how trailer blocks are found (beyond the simple case in the introduction), and how the end of the message is found.
Also note that we simplify the “blank line” point. The text says:
A blank line will be added before the new trailer if there isn't one already.
But this isn’t quite coherent. The previous sentence says “If there is no existing trailer”, so we are in one of these modes:
1. discussing trailer blocks in general; or
2. discussing creating a new trailer block in particular.
If (1), then we shouldn’t add a blank line before the new trailer if there exists a trailer block already. And if (2), then the “if there isn’t one already” is redundant.[2] So just talking about the higher- level “trailer block” simplifies the text, since we don’t have to worry about the different contexts that *trailers* can find themselves in.
† 1: in commit “explain the format after the intro”
† 2: Note that non-trailer lines don’t matter here; if you have a
trailer block consisting of (cherry picked from commit <commit>), then you still shouldn’t insert a blank line before the new trailer since that would create a new trailer block
---
Notes (series):
v4:
• Tweak “blank line” reminder (“Recall that”) by dropping “specifically” since it is redundant based on [1]. Well, I thought I understood the feedback here but reading it again today I was confused. @Junio, did I understand it correctly?
My thought process: This “recall that” is similar to other “recall” phrases added in the series. They add some redundancy, similar in spirit to 74522b6b (Documentation/git-update-ref.txt:
discuss symbolic refs, 2024-10-21) :
| Add a paragraph which just emphasizes that the command without | any options does not support refs in the final arguments. This | is clear already from the names <new-oid> and <old-oid> but | the right balance of redundancy makes documentation robust | against stray interpretation.
• Msg: Editing the above I noticed that the previous (before this change “blank line” explanation isn’t (quite) coherent. I want to explain every meaningful point of change in the commit message, so I dedicate some “also” paragraphs to that change.
• For [1] again: s/Concretely, that/A trailer block/ since it flows better
• For [1] again: Fix mangled “The trailer block is by definition” sentence and make sure to use “commit message”. We use “commit message” throughout the doc, not just “message”. But just use “message” in the next sentence since it is clear that we are still talking about *commit* message.
• Msg: Reflow existing paragraph
🔗 1: https://lore.kernel.org/git/[email protected]/#t
---
v2: [new]
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-)
Documentation/git-interpret-trailers.adoc +14 -12
@@ -74,19 +74,21 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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. - -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 +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 will be inserted before the +new trailer block in that case. + +Existing trailers are extracted from the input by looking for the +trailer block. A trailer block 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 of the commit message. +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). For convenience, a _<key-alias>_ can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 10/11 doc: interpret-trailers: rewrite new-trailers paragraphs
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Two commits ago we moved new-trailers paragraph next to each other. But there is something curious about two of them:
By default the new trailer will appear at the end of the trailer block. [...]
Then a source block and a paragraph later:
By default, a <key>=<value> or <key>:<value> argument given using --trailer will be appended after the existing trailers only if [...]
Why are there two paragraphs that talk about how “By default” a trailer will be appended?
We can make these paragraphs flow better, and with a more distinct character each, by dividing the flow like this:
1. Declare that we are about to talk about --trailer appending
2. Explain the default behavior
3. Explain how this affects the trailer block
4. Then discuss what each trailer line will look like
---
Notes (series):
v4:
• Simplify “This is how the new trailer” paragraph: drop “More concretely,” since it is misleading (this is not a “more concretely continuation of the preceding paragraph(s))[1]
🔗 1: https://lore.kernel.org/git/[email protected]/
---
v3: [new]
• Based on draft: https://lore.kernel.org/git/[email protected]/
• See msg:
Two commits ago we moved new-trailers paragraph next to each other.
This commit here might fit better one step back. So that it becomes the commit right after. But I can deal with that commit movement if this change is accepted. For now I didn’t bother.
Documentation/git-interpret-trailers.adoc | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-)
Documentation/git-interpret-trailers.adoc +12 -10
@@ -60,10 +60,18 @@ are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers. -By default, a `<key>=<value>` or `<key>:<value>` argument given -using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed +Let's consider new trailers added with `--trailer`. +By default, the new trailer will appear at the end of the trailer block. +Also by default, this new trailer will only be added +if the last trailer is different to it. +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 will be inserted before the +new trailer block in that case. + +This is how the new trailer is added: a `<key>=<value>` or +`<key>:<value>` argument given using `--trailer` will be appended after +the existing trailers. The _<key>_ and _<value>_ parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed _<key>_ and _<value>_ will appear in the output like this:
@@ -74,12 +82,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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 will be inserted before the -new trailer block in that case. - Existing trailers are extracted from the input by looking for the trailer block. A trailer block is a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or
Signature · 1 line
2.54.0.22.g9e26862b904
PATCH v5 11/11 doc: interpret-trailers: document comment line treatment
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Comment lines have always been ignored but this is not documented.
The primary motivation here is to be reasonably complete in the documentation of how trailers are parsed; this is after all the only documentation page that documents this format. However, and going beyond that point, we could imagine that someone would want to use this format outside a commit (or tag) message context, like say in Git notes.
On the other hand, it seems far-fetched that someone would be caught off guard by this considering that comment characters/strings are not likely to be alphanumeric,[1] which would mean that these comment lines would be treated as non-trailer lines if they were *not* detected and removed as comment lines.
† 1: A notable exception is that Jujutsu VCS uses JJ: as
the comment string
---
Notes (series):
v5:
• Msg: add missing word: s/to/to be/[1]
🔗 1: https://lore.kernel.org/git/CALnO6CB_0ucqnAowrNcPmsXmxxDfJQZPVGkbsHVuya7NLR4dsg@mail.gmail.com/
---
v4:
• Msg: rewrite motivation for documenting this. The motivation is not super solid, but it reflects my own ambiguity on the matter, so to speak; I think we ought to be very thorough about documenting the format, while making sure to not use the main text to exhaustively lay it all out. The information should be somewhere in this doc. But not in your face.
• Msg: Add “(or tag) message”. See patch “not just for commit messages” where trailer support for tag messages are mentioned.
---
v3:
• Msg: finally fix area
• Demote this point to its own “other rules” section, out of the main running text. It is not important enough for the main text.
• Since writing this I have realized that we can go into that long
# ----- >8 ----
Commit message separator scissor line, maybe other things. But I stop short here. These things are even less likely to become a problem for anyone. And maybe we’ll add them later?
v2: [new]
Documentation/git-interpret-trailers.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+)
Documentation/git-interpret-trailers.adoc +10 -0
@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and newlines in it. ------------------------------------------------ +OTHER RULES +----------- + +What was covered in the previous section are the rules that are relevant +for regular use. The following points are included for completeness. + +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. + OPTIONS ------- `--in-place`::
Signature · 1 line
2.54.0.22.g9e26862b904
Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format
In reply to [email protected]Quoted 109 lines · Le 9 août 2026 à 16:07, [email protected] a écrit :
From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.
Here one change lead to another in order to make sure that everything stayed coherent. So here’s a linear overview of the changes (as of v4):
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain the “key” format, and add a new example
• Patch 8: join some existing paragraphs that are about the same theme since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in patch 5 later in the doc
• Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behaviorThanks to everyone who has been reviewing these so far. I understand that these eleven changes are very incremental and piecemeal (see “very cross-referenced commit messages”). And the commit messages can be quite long, just to explain (again) very small changes. See for example patch “replace “lines” with “metadata”” in this version, where I explain why to write “trailer metadata” instead of “trailers metadata”. But right now I feel like prose sometimes needs all this ceremony. With code you get restraints like coding style, then you have all the years of looser rules about when to use certain data structures, when to make helper methods, etc. But with prose it seems that you bring much more of your individuality to it. That means more choices, and many of them are not obvious to the reader of the document, which means that you need to explain it in the commit message. Then you also have to consider the writing history of the document, and this one is twelve years old at this point; see the history review in commit message “join new-trailers again”, after the thematic break (***).
§ Changes in v5
Patch “document comment line treatment”: commit message: add missing word:
s/to/to be/.§ Apologies for very cross-referenced commit messages
(see v3)
§ Cc
(see v2)
https://lore.kernel.org/git/[email protected]/
I have also added a new email since the email [email protected] bounces for me. There is a Brendan Jackman who has posted messages under a Gmail address. Hopefully it’s the same person.
§ In-reply-to: v1
The recommendation to reply to the first version/cover letter is from topic ps/doc-recommend-b4, which is in
nextright now.§ Link to v4
https://lore.kernel.org/git/[email protected]/
[01/11] doc: interpret-trailers: stop fixating on RFC 822 [02/11] doc: interpret-trailers: replace “lines” with “metadata” [03/11] doc: interpret-trailers: use “metadata” in Name as well [04/11] doc: interpret-trailers: not just for commit messages [05/11] doc: interpret-trailers: explain the format after the intro [06/11] doc: interpret-trailers: explain key format [07/11] doc: interpret-trailers: add key format example [08/11] doc: interpret-trailers: join new-trailers again [09/11] doc: interpret-trailers: commit to “trailer block” term [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs [11/11] doc: interpret-trailers: document comment line treatment
Documentation/git-interpret-trailers.adoc| 88 ++++++++++++++++-------1 file changed, 64 insertions(+), 24 deletions(-)Interdiff against v4:
Range-diff against v4:1: 2419b1a6863 = 1: 2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822 2: 859ab42ac41 = 2: 859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata” 3: ab5b4af970e = 3: ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well 4: b79ddf3b13e = 4: b79ddf3b13e doc: interpret-trailers: not just for commit messages 5: e7101eb1fcb = 5: e7101eb1fcb doc: interpret-trailers: explain the format after the intro 6: 557b5b5564a = 6: 557b5b5564a doc: interpret-trailers: explain key format 7: eee81fc99fa = 7: eee81fc99fa doc: interpret-trailers: add key format example 8: cd3e47459c7 = 8: cd3e47459c7 doc: interpret-trailers: join new-trailers again 9: c50b6d25170 = 9: c50b6d25170 doc: interpret-trailers: commit to “trailer block” term 10: c11a116605e = 10: c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs 11: 7d20cb7528f ! 11: cabbb05a1c4 doc: interpret-trailers: document comment line treatment@@ Commit message
Comment lines have always been ignored but this is not documented.
- The primary motivation here is to reasonably complete in the
+ The primary motivation here is to be reasonably complete in the
documentation of how trailers are parsed; this is after all the only documentation page that documents this format. However, and going beyond that point, we could imagine that someone would want to use this format
Quoted 3 lines
base-commit:
5361983c075154725be47b65cca9a2421789e410--
2.54.0.22.g9e26862b904
I’m trivially satisfied with the range-diff (note again I’ve reviewed primarily the end result, not the per-commit history).
Best,
Ben
Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format
Quoted 4 lines · Ben Knoble
Quoted 2 lines · Le 9 août 2026 à 16:07, [email protected] a écrit :
[snip]
I’m trivially satisfied with the range-diff (note again I’ve reviewed primarily the end result, not the per-commit history).
Thank you for the review and for sticking
with this series.
Kris
sent from mobile
Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format
In reply to Ben KnobleQuoted 15 lines · Ben Knoble
Quoted 15 lines
§ Link to v4
https://lore.kernel.org/git/[email protected]/
[01/11] doc: interpret-trailers: stop fixating on RFC 822 [02/11] doc: interpret-trailers: replace “lines” with “metadata” [03/11] doc: interpret-trailers: use “metadata” in Name as well [04/11] doc: interpret-trailers: not just for commit messages [05/11] doc: interpret-trailers: explain the format after the intro [06/11] doc: interpret-trailers: explain key format [07/11] doc: interpret-trailers: add key format example [08/11] doc: interpret-trailers: join new-trailers again [09/11] doc: interpret-trailers: commit to “trailer block” term [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs [11/11] doc: interpret-trailers: document comment line treatment
[...]
Quoted 10 lines
Quoted 10 lines
@@ Commit message
Comment lines have always been ignored but this is not documented.
- The primary motivation here is to reasonably complete in the
+ The primary motivation here is to be reasonably complete in the
documentation of how trailers are parsed; this is after all the only documentation page that documents this format. However, and going beyond that point, we could imagine that someone would want to use this format
Quoted 5 lines
Quoted 3 lines
base-commit:
5361983c075154725be47b65cca9a2421789e410--
2.54.0.22.g9e26862b904I’m trivially satisfied with the range-diff (note again I’ve reviewed primarily the end result, not the per-commit history).
Heh, that is like saying it is better with "be" than without ;-).
I think the topic was already in pretty good shape by 'v4'. Shall we declare victory and mark the topic for 'next'?
Thanks.