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

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Sun, 24 May 2026 14:41:01 +0200

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]