Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format
Show 8 quoted lines
> 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 :)
Show 111 quoted lines
>>> [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.
Show 39 quoted lines
> ***
>
> 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]