* [PATCH v2 1/9] doc: interpret-trailers: stop fixating on RFC 822
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 2/9] doc: interpret-trailers: replace “lines” with “metadata” kristofferhaugsbakk
` (8 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
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(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 77b4f63b05c..1878848ad2a 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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`::
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 2/9] doc: interpret-trailers: replace “lines” with “metadata”
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 1/9] doc: interpret-trailers: stop fixating on RFC 822 kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 3/9] doc: interpret-trailers: use “metadata” in Name as well kristofferhaugsbakk
` (7 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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)
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 1878848ad2a..3f60fd9b720 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 3/9] doc: interpret-trailers: use “metadata” in Name as well
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 1/9] doc: interpret-trailers: stop fixating on RFC 822 kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 2/9] doc: interpret-trailers: replace “lines” with “metadata” kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 4/9] doc: interpret-trailers: not just for commit messages kristofferhaugsbakk
` (6 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 3f60fd9b720..4e92c8299bb 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -3,7 +3,7 @@ git-interpret-trailers(1)
NAME
----
-git-interpret-trailers - Add or parse structured information in commit messages
+git-interpret-trailers - Add or parse metadata in commit messages
SYNOPSIS
--------
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 4/9] doc: interpret-trailers: not just for commit messages
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (2 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 3/9] doc: interpret-trailers: use “metadata” in Name as well kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 5/9] doc: interpret-trailers: explain the format after the intro kristofferhaugsbakk
` (5 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 4e92c8299bb..7329e710e1a 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 5/9] doc: interpret-trailers: explain the format after the intro
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (3 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 4/9] doc: interpret-trailers: not just for commit messages kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 6/9] doc: interpret-trailers: explain key format kristofferhaugsbakk
` (4 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D. Ben Knoble
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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)
Suggested-by: D. Ben Knoble <ben.knoble+github@gmail•com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 7329e710e1a..bcd79b19bd7 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 6/9] doc: interpret-trailers: explain key format
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (4 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 5/9] doc: interpret-trailers: explain the format after the intro kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 7/9] doc: interpret-trailers: add key format example kristofferhaugsbakk
` (3 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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
Reported-by: Brendan Jackman <jackmanb@google•com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
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(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index bcd79b19bd7..c35fa9c688d 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 7/9] doc: interpret-trailers: add key format example
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (5 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 6/9] doc: interpret-trailers: explain key format kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 8/9] doc: interpret-trailers: commit to “trailer block” term kristofferhaugsbakk
` (2 subsequent siblings)
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index c35fa9c688d..f215cba4bf0 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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 <alice@example•com>
+$ git interpret-trailers --only-trailers <msg.txt
+$
+----
++
+Recall that a trailer key has to consist of only ASCII alphanumeric
+characters and hyphens, and this does not hold for the two first
+supposed trailer keys. And now none are recognized as trailers because
+the candidate trailer block has at least one non-trailer line, even
+though `Reviewed-by` is a valid trailer key. Recall that a trailer block
+has to either (i) be all trailers, or (ii) consist of at least one
+Git-generated or user-configured trailer (and some other conditions).
+And (ii) is not satisfied since we have not configured any trailer keys.
+
SEE ALSO
--------
linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 8/9] doc: interpret-trailers: commit to “trailer block” term
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (6 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 7/9] doc: interpret-trailers: add key format example kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment kristofferhaugsbakk
2026-05-08 15:01 ` [PATCH v2 0/9] doc: interpret-trailers: explain key format Kristoffer Haugsbakk
9 siblings, 0 replies; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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”
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index f215cba4bf0..b693e89fd96 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (7 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 8/9] doc: interpret-trailers: commit to “trailer block” term kristofferhaugsbakk
@ 2026-04-13 10:21 ` kristofferhaugsbakk
2026-04-13 13:26 ` Kristoffer Haugsbakk
2026-05-08 15:01 ` [PATCH v2 0/9] doc: interpret-trailers: explain key format Kristoffer Haugsbakk
9 siblings, 1 reply; 33+ messages in thread
From: kristofferhaugsbakk @ 2026-04-13 10:21 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver
From: Kristoffer Haugsbakk <code@khaugsbakk•name>
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.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk•name>
---
Notes (series):
v2: [new]
| 4 ++++
1 file changed, 4 insertions(+)
--git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index b693e89fd96..b42f957d666 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -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,
--
2.53.0.32.gf6228eaf9cc
^ permalink raw reply related [flat|nested] 33+ messages in thread* Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
2026-04-13 10:21 ` [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment kristofferhaugsbakk
@ 2026-04-13 13:26 ` Kristoffer Haugsbakk
2026-04-13 15:48 ` Junio C Hamano
0 siblings, 1 reply; 33+ messages in thread
From: Kristoffer Haugsbakk @ 2026-04-13 13:26 UTC (permalink / raw)
To: git; +Cc: Christian Couder, jackmanb, Linus Arver
> [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
s/intepret-trailers/interpret-trailers/
Didn’t line up
On Mon, Apr 13, 2026, at 12:21, kristofferhaugsbakk@fastmail•com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk•name>
>[snip]
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
2026-04-13 13:26 ` Kristoffer Haugsbakk
@ 2026-04-13 15:48 ` Junio C Hamano
2026-05-08 15:03 ` Kristoffer Haugsbakk
0 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2026-04-13 15:48 UTC (permalink / raw)
To: Kristoffer Haugsbakk; +Cc: git, Christian Couder, jackmanb, Linus Arver
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com> writes:
>> [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.
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment
2026-04-13 15:48 ` Junio C Hamano
@ 2026-05-08 15:03 ` Kristoffer Haugsbakk
0 siblings, 0 replies; 33+ messages in thread
From: Kristoffer Haugsbakk @ 2026-05-08 15:03 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Christian Couder, jackmanb, Linus Arver, D. Ben Knoble
On Mon, Apr 13, 2026, at 17:48, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com> writes:
>
>>> [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.
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
` (8 preceding siblings ...)
2026-04-13 10:21 ` [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment kristofferhaugsbakk
@ 2026-05-08 15:01 ` Kristoffer Haugsbakk
2026-05-11 2:41 ` Junio C Hamano
9 siblings, 1 reply; 33+ messages in thread
From: Kristoffer Haugsbakk @ 2026-05-08 15:01 UTC (permalink / raw)
To: git; +Cc: Christian Couder, jackmanb, Linus Arver, D. Ben Knoble
On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail•com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk•name>
>[snip]
Sorry to Ben here who I forgot to set on copy. :/
+Cc now.
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-05-08 15:01 ` [PATCH v2 0/9] doc: interpret-trailers: explain key format Kristoffer Haugsbakk
@ 2026-05-11 2:41 ` Junio C Hamano
2026-05-11 19:23 ` D. Ben Knoble
0 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2026-05-11 2:41 UTC (permalink / raw)
To: Kristoffer Haugsbakk
Cc: git, Christian Couder, jackmanb, Linus Arver, D. Ben Knoble
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com> writes:
> On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail•com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk•name>
>>[snip]
>
> Sorry to Ben here who I forgot to set on copy. :/
>
> +Cc now.
It has been quite a while and I have no recollection if there were
still necessary adjustments or not. Is everybody happy with the
final text?
https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/
Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++--------
1 file changed, 50 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 77b4f63b05..b42f957d66 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -3,7 +3,7 @@ git-interpret-trailers(1)
NAME
----
-git-interpret-trailers - Add or parse structured information in commit messages
+git-interpret-trailers - Add or parse metadata in commit messages
SYNOPSIS
--------
@@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]
DESCRIPTION
-----------
-Add or parse _trailer_ lines that look similar to RFC 822 e-mail
-headers, at the end of the otherwise free-form part of a commit
-message. For example, in the following commit message
+Add or parse trailers metadata at the end of the otherwise
+free-form part of a commit message, or any other kind of text.
+
+A _trailer_ in its simplest form is a key-value pair with a colon as a
+separator. The _key_ consists of ASCII alphanumeric characters and
+hyphens (`-`). A _trailer block_ consists of one or more trailers. The
+trailer block needs to be preceded by a blank line, where a _blank line_
+is either an empty or a whitespace-only line. For example, in the
+following commit message
------------------------------------------------
subject
@@ -81,19 +87,25 @@ trailer.sign.key "Signed-off-by: "
in your configuration, you only need to specify `--trailer="sign: foo"`
on the command line instead of `--trailer="Signed-off-by: foo"`.
-By default the new trailer will appear at the end of all the existing
-trailers. If there is no existing trailer, the new trailer will appear
-at the end of the input. A blank line will be added before the new
-trailer if there isn't one already.
+By default the new trailer will appear at the end of the trailer block.
+A trailer block will be created with only that trailer if a trailer
+block does not already exist. Recall that a trailer block needs to be
+preceded by a blank line, so a blank line (specifically an empty line)
+will be inserted before the new trailer block in that case.
-Existing trailers are extracted from the input by looking for
-a group of one or more lines that (i) is all trailers, or (ii) contains at
-least one Git-generated or user-configured trailer and consists of at
+Existing trailers are extracted from the input by looking for the
+trailer block. Concretely, that is a group of one or more lines that (i)
+is all trailers, or (ii) contains at least one Git-generated or
+user-configured trailer and consists of at
least 25% trailers.
-The group must be preceded by one or more empty (or whitespace-only) lines.
-The group must either be at the end of the input or be the last
-non-whitespace lines before a line that starts with `---` (followed by a
-space or the end of the line).
+The trailer block is by definition at the end the the message. The end
+of the message in turn is either (i) at the end of the input, or (ii)
+the last non-whitespace lines before a line that starts with `---`
+(followed by a space or the end of the line).
+
+This command ignores comment lines (see `core.commentString` in
+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
+and `commit-msg` hooks.
When reading trailers, there can be no whitespace before or inside the
_<key>_, but any number of regular space and tab characters are allowed
@@ -107,9 +119,6 @@ key: This is a very long value, with spaces and
newlines in it.
------------------------------------------------
-Note that trailers do not follow (nor are they intended to follow) many of the
-rules for RFC 822 headers. For example they do not follow the encoding rule.
-
OPTIONS
-------
`--in-place`::
@@ -402,6 +411,29 @@ mv "\$1.new" "\$1"
$ chmod +x .git/hooks/commit-msg
------------
+* Here we try to to use three different trailer keys. But it fails
+ because two of them are not recognized as trailer keys.
++
+----
+$ cat msg.txt
+subject
+
+Skapad-på: some-branch
+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c
+Reviewed-by: Alice <alice@example•com>
+$ git interpret-trailers --only-trailers <msg.txt
+$
+----
++
+Recall that a trailer key has to consist of only ASCII alphanumeric
+characters and hyphens, and this does not hold for the two first
+supposed trailer keys. And now none are recognized as trailers because
+the candidate trailer block has at least one non-trailer line, even
+though `Reviewed-by` is a valid trailer key. Recall that a trailer block
+has to either (i) be all trailers, or (ii) consist of at least one
+Git-generated or user-configured trailer (and some other conditions).
+And (ii) is not satisfied since we have not configured any trailer keys.
+
SEE ALSO
--------
linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
^ permalink raw reply related [flat|nested] 33+ messages in thread
* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-05-11 2:41 ` Junio C Hamano
@ 2026-05-11 19:23 ` D. Ben Knoble
2026-05-24 12:41 ` Kristoffer Haugsbakk
0 siblings, 1 reply; 33+ messages in thread
From: D. Ben Knoble @ 2026-05-11 19:23 UTC (permalink / raw)
To: Junio C Hamano
Cc: Kristoffer Haugsbakk, git, Christian Couder, jackmanb,
Linus Arver
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.
On Sun, May 10, 2026 at 10:41 PM Junio C Hamano <gitster@pobox•com> wrote:
>
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com> writes:
>
> > On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail•com wrote:
> >> From: Kristoffer Haugsbakk <code@khaugsbakk•name>
> >>[snip]
> >
> > Sorry to Ben here who I forgot to set on copy. :/
> >
> > +Cc now.
>
> It has been quite a while and I have no recollection if there were
> still necessary adjustments or not. Is everybody happy with the
> final text?
>
> https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/
>
>
> Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++--------
> 1 file changed, 50 insertions(+), 18 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
> index 77b4f63b05..b42f957d66 100644
> --- a/Documentation/git-interpret-trailers.adoc
> +++ b/Documentation/git-interpret-trailers.adoc
> @@ -3,7 +3,7 @@ git-interpret-trailers(1)
>
> NAME
> ----
> -git-interpret-trailers - Add or parse structured information in commit messages
> +git-interpret-trailers - Add or parse metadata in commit messages
>
> SYNOPSIS
> --------
> @@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]
>
> DESCRIPTION
> -----------
> -Add or parse _trailer_ lines that look similar to RFC 822 e-mail
> -headers, at the end of the otherwise free-form part of a commit
> -message. For example, in the following commit message
> +Add or parse trailers metadata at the end of the otherwise
> +free-form part of a commit message, or any other kind of text.
> +
> +A _trailer_ in its simplest form is a key-value pair with a colon as a
> +separator. The _key_ consists of ASCII alphanumeric characters and
> +hyphens (`-`). A _trailer block_ consists of one or more trailers. The
> +trailer block needs to be preceded by a blank line, where a _blank line_
> +is either an empty or a whitespace-only line. For example, in the
> +following commit message
>
> ------------------------------------------------
> subject
> @@ -81,19 +87,25 @@ trailer.sign.key "Signed-off-by: "
> in your configuration, you only need to specify `--trailer="sign: foo"`
> on the command line instead of `--trailer="Signed-off-by: foo"`.
>
> -By default the new trailer will appear at the end of all the existing
> -trailers. If there is no existing trailer, the new trailer will appear
> -at the end of the input. A blank line will be added before the new
> -trailer if there isn't one already.
> +By default the new trailer will appear at the end of the trailer block.
> +A trailer block will be created with only that trailer if a trailer
> +block does not already exist. Recall that a trailer block needs to be
> +preceded by a blank line, so a blank line (specifically an empty line)
> +will be inserted before the new trailer block in that case.
[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.
> -Existing trailers are extracted from the input by looking for
> -a group of one or more lines that (i) is all trailers, or (ii) contains at
> -least one Git-generated or user-configured trailer and consists of at
> +Existing trailers are extracted from the input by looking for the
> +trailer block. Concretely, that is a group of one or more lines that (i)
> +is all trailers, or (ii) contains at least one Git-generated or
> +user-configured trailer and consists of at
> least 25% trailers.
> -The group must be preceded by one or more empty (or whitespace-only) lines.
> -The group must either be at the end of the input or be the last
> -non-whitespace lines before a line that starts with `---` (followed by a
> -space or the end of the line).
> +The trailer block is by definition at the end the the message. The end
> +of the message in turn is either (i) at the end of the input, or (ii)
> +the last non-whitespace lines before a line that starts with `---`
> +(followed by a space or the end of the line).
> +
> +This command ignores comment lines (see `core.commentString` in
> +linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
> +and `commit-msg` hooks.
>
> When reading trailers, there can be no whitespace before or inside the
> _<key>_, but any number of regular space and tab characters are allowed
> @@ -107,9 +119,6 @@ key: This is a very long value, with spaces and
> newlines in it.
> ------------------------------------------------
>
> -Note that trailers do not follow (nor are they intended to follow) many of the
> -rules for RFC 822 headers. For example they do not follow the encoding rule.
> -
> OPTIONS
> -------
> `--in-place`::
> @@ -402,6 +411,29 @@ mv "\$1.new" "\$1"
> $ chmod +x .git/hooks/commit-msg
> ------------
>
> +* Here we try to to use three different trailer keys. But it fails
> + because two of them are not recognized as trailer keys.
> ++
> +----
> +$ cat msg.txt
> +subject
> +
> +Skapad-på: some-branch
> +Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c
> +Reviewed-by: Alice <alice@example•com>
> +$ git interpret-trailers --only-trailers <msg.txt
> +$
> +----
> ++
> +Recall that a trailer key has to consist of only ASCII alphanumeric
> +characters and hyphens, and this does not hold for the two first
> +supposed trailer keys. And now none are recognized as trailers because
> +the candidate trailer block has at least one non-trailer line, even
> +though `Reviewed-by` is a valid trailer key. Recall that a trailer block
> +has to either (i) be all trailers, or (ii) consist of at least one
> +Git-generated or user-configured trailer (and some other conditions).
> +And (ii) is not satisfied since we have not configured any trailer keys.
> +
> SEE ALSO
> --------
> linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-05-11 19:23 ` D. Ben Knoble
@ 2026-05-24 12:41 ` Kristoffer Haugsbakk
2026-05-26 21:34 ` Ben Knoble
0 siblings, 1 reply; 33+ messages in thread
From: Kristoffer Haugsbakk @ 2026-05-24 12:41 UTC (permalink / raw)
To: D. Ben Knoble, Junio C Hamano
Cc: git, Christian Couder, jackmanb, Linus Arver
On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:
> 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. :)
>>[snip]
>> @@ -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.
>
> [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.
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)
> 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).
***
>[snip]
>> -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
>>[snip]
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-05-24 12:41 ` Kristoffer Haugsbakk
@ 2026-05-26 21:34 ` Ben Knoble
2026-05-26 21:42 ` Kristoffer Haugsbakk
0 siblings, 1 reply; 33+ messages in thread
From: Ben Knoble @ 2026-05-26 21:34 UTC (permalink / raw)
To: Kristoffer Haugsbakk
Cc: Junio C Hamano, git, Christian Couder, jackmanb, Linus Arver
> Le 24 mai 2026 à 08:41, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail•com> a écrit :
>
> On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:
>> 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 :)
>>> [snip]
>>> @@ -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.
>>
>> [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.
>
> 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)
>
>> 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.
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.
> ***
>
> 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).
>
> ***
>
>> [snip]
>>> -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
>>> [snip]
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-05-26 21:34 ` Ben Knoble
@ 2026-05-26 21:42 ` Kristoffer Haugsbakk
2026-05-26 21:45 ` Kristoffer Haugsbakk
0 siblings, 1 reply; 33+ messages in thread
From: Kristoffer Haugsbakk @ 2026-05-26 21:42 UTC (permalink / raw)
To: D. Ben Knoble
Cc: Junio C Hamano, git, Christian Couder, jackmanb, Linus Arver
On Tue, May 26, 2026, at 23:34, Ben Knoble wrote:
>> Le 24 mai 2026 à 08:41, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail•com> a écrit :
>>
>> On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:
>>> 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 :)
>
>>[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.
>
> 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!
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
2026-05-26 21:42 ` Kristoffer Haugsbakk
@ 2026-05-26 21:45 ` Kristoffer Haugsbakk
0 siblings, 0 replies; 33+ messages in thread
From: Kristoffer Haugsbakk @ 2026-05-26 21:45 UTC (permalink / raw)
To: D. Ben Knoble
Cc: Junio C Hamano, git, Christian Couder, jackmanb, Linus Arver
On Tue, May 26, 2026, at 23:42, Kristoffer Haugsbakk wrote:
>>[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.
^ permalink raw reply [flat|nested] 33+ messages in thread