git-interpret-trailers and period characters in the key

git-interpret-trailers and period characters in the key

[Brendan Jackman]

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)

Re: git-interpret-trailers and period characters in the key

[Christian Couder]

Hi,

On Tue, Apr 1, 2025 at 3:27 PM Brendan Jackman <jackmanb@google.com> wrote:

> 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.

> 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.

Re: git-interpret-trailers and period characters in the key

[Junio C Hamano]

Christian Couder <christian.couder@gmail.com> writes:

> 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.

[PATCH 0/2] doc: interpret-trailers: explain key format

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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
-- 
2.53.0.32.gf6228eaf9cc

[PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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(-)

diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 77b4f63b05c..e7c1f821619 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_ 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`::
-- 
2.53.0.32.gf6228eaf9cc

[PATCH 2/2] doc: interpret-trailers: explain key format

[kristofferhaugsbakk]

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 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>).

Reported-by: Brendan Jackman <jackmanb@google.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

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(-)

diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index e7c1f821619..92d9c95f9d2 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -27,7 +27,10 @@ Signed-off-by: Alice <alice@example.com>
 Signed-off-by: Bob <bob@example.com>
 ------------------------------------------------
 
-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.
-- 
2.53.0.32.gf6228eaf9cc

Re: [PATCH 2/2] doc: interpret-trailers: explain key format

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> 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 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.

> 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 ;-)

> 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.

> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
> index e7c1f821619..92d9c95f9d2 100644
> --- a/Documentation/git-interpret-trailers.adoc
> +++ b/Documentation/git-interpret-trailers.adoc
> @@ -27,7 +27,10 @@ Signed-off-by: Alice <alice@example.com>
>  Signed-off-by: Bob <bob@example.com>
>  ------------------------------------------------
>  
> -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.

> +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

[Kristoffer Haugsbakk]

On Mon, Mar 30, 2026, at 23:55, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
>
>> 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 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.

>> 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 ;-)
>
>> 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.

>
>> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
>> index e7c1f821619..92d9c95f9d2 100644
>> --- a/Documentation/git-interpret-trailers.adoc
>> +++ b/Documentation/git-interpret-trailers.adoc
>> @@ -27,7 +27,10 @@ Signed-off-by: Alice <alice@example.com>
>>  Signed-off-by: Bob <bob@example.com>
>>  ------------------------------------------------
>>
>> -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.

>
>> +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.

I’ll take the first one here.

Thank you!

Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com 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 ;-)

> @@ -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

[Kristoffer Haugsbakk]

On Tue, Mar 31, 2026, at 00:27, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com 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.

>, as the two paragraphs before and after are not all that unrelated.

Or nothing.

> 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 ;-)

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).

>[snip]

Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> 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.

Re: [PATCH 2/2] doc: interpret-trailers: explain key format

[Ben Knoble]

> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> a écrit :
> 
> On Mon, Mar 30, 2026, at 23:55, Junio C Hamano wrote:
>> kristofferhaugsbakk@fastmail.com 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.
> 
> 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

[Kristoffer Haugsbakk]

On Tue, Mar 31, 2026, at 14:35, Ben Knoble wrote:
>> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> a écrit :
>>>[snip]
>>
>> 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.
>
> 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!

> 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/xmqqmt2emwlj.fsf@gitster.g/
† 2: `git show d57fa7fc73202af226b6c0^1:Documentation/git-interpret-trailers.txt`

> 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.

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>
------------------------------------------------

***

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

[PATCH v2 0/9] doc: interpret-trailers: explain key format

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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/CV_doc_int-tr_key_format.533@msgid.xyz/#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:
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 92d9c95f9d2..b42f957d666 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_ 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 <alice@example.com>
 Signed-off-by: Bob <bob@example.com>
 ------------------------------------------------
 
-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 <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]

base-commit: 5361983c075154725be47b65cca9a2421789e410
-- 
2.53.0.32.gf6228eaf9cc

[PATCH v2 1/9] doc: interpret-trailers: stop fixating on RFC 822

[kristofferhaugsbakk]

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

[PATCH v2 2/9] doc: interpret-trailers: replace “lines” with “metadata”

[kristofferhaugsbakk]

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

[PATCH v2 3/9] doc: interpret-trailers: use “metadata” in Name as well

[kristofferhaugsbakk]

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

[PATCH v2 4/9] doc: interpret-trailers: not just for commit messages

[kristofferhaugsbakk]

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

[PATCH v2 5/9] doc: interpret-trailers: explain the format after the intro

[kristofferhaugsbakk]

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

[PATCH v2 6/9] doc: interpret-trailers: explain key format

[kristofferhaugsbakk]

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

[PATCH v2 7/9] doc: interpret-trailers: add key format example

[kristofferhaugsbakk]

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

[PATCH v2 8/9] doc: interpret-trailers: commit to “trailer block” term

[kristofferhaugsbakk]

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

[PATCH v2 9/9] doc: intepret-trailers: document comment line treatment

[kristofferhaugsbakk]

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]

 Documentation/git-interpret-trailers.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --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

Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment

[Kristoffer Haugsbakk]

> [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]

Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment

[Junio C Hamano]

"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.

Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format

[Kristoffer Haugsbakk]

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.

Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment

[Kristoffer Haugsbakk]

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.

Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format

[Junio C Hamano]

"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]

Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format

[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.

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