Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Thu, Jun 11, 2026, at 00:24, Junio C Hamano wrote:
>[snip]
>> +A trailer block will be created with only that trailer if a trailer
>> +block does not already exist. Recall that a trailer block needs to be
>> +preceded by a blank line, so a blank line (specifically an empty line)
>> +will be inserted before the new trailer block in that case.
>
> If you want to stress that a line with only whitespaces on it does
> not count as a blank line for the purpose of this paragraph, you can
> consistently say "an empty line" withotu saying "a blank line", and
> you do not need to have "(specifically an empty lline)" there.

Okay, I’ll make it shorter.

It felt too long for a simple concept indeed.

>
>> +More concretely, this is how the new trailer is added: a `<key>=<value>`
>> +or `<key>:<value>` argument given using `--trailer` will be appended
>> +after the existing trailers. The _<key>_ and _<value>_ parts will be
>> +trimmed to remove starting and trailing whitespace, and the resulting
>> +trimmed _<key>_ and _<value>_ will appear in the output like this:
>
> "More concretely" here feels a bit out of place, as the three paragraphs
> we saw so far aren't really progression of the same thing.  First we
> saw when a new trailer line is added, second we learned that an
> extra empty line may be added in addition to the new trailer line.
> What we are about to mention is orthogonal: how each trailer line
> would look like.  There is no more or less concrete about it.

Yeah, I think I see. I thought this would be continuation into the more
nuts and bolts of it, where we move from discussing the concepts to the
concrete placeholders, so to speak.

I thought I needed a phrase to connect the paragraphs. But now I don’t
think I do. Just dropping that phrase:

    Let's consider new trailers added with `--trailer`.
    By default, the new trailer will appear at the end of the trailer block.
    Also by default, this new trailer will only be added
    if the last trailer is different to it.
    A trailer block will be created with only that trailer if a trailer
    block does not already exist. Recall that a trailer block needs to be
    preceded by a blank line, so a blank line (specifically an empty line)
    will be inserted before the new trailer block in that case.

    This is how the new trailer is added: a `<key>=<value>`
    or `<key>:<value>` argument given using `--trailer` will be appended
    after the existing trailers. The _<key>_ and _<value>_ parts will be
    trimmed to remove starting and trailing whitespace, and the resulting
    trimmed _<key>_ and _<value>_ will appear in the output like this:

And it still flows.

>
>>  ------------------------------------------------
>>  key: value
>> @@ -74,6 +82,16 @@ key: value
>>  This means that the trimmed _<key>_ and _<value>_ will be separated by
>>  "`:`{nbsp}" (one colon followed by one space).
>>
>> +Existing trailers are extracted from the input by looking for the
>> +trailer block. Concretely, that is a group of one or more lines that (i)
>
> "Concretely, that is a" -> "A trailer block is a".

Yeah. That seems simpler.

Replacing “that” with what it represents, namely “A trailer block”.

Sometimes just repeating the noun can feel stuttery, like the sentences
don’t flow. But there is enough variation here; the previous sentence
ends with “the trailer block” (definitive), and the next sentence takes
a step back and talks about the indefinitive (a trailer block).

>
>> +is all trailers, or (ii) contains at least one Git-generated or
>> +user-configured trailer and consists of at
>> +least 25% trailers.
>
> Hmph, isn't (i) a narrow subset of (ii)?

Well, this text modulo a grammatical fix goes back all the way to the
implementation of the 25% rule in 14624506 (trailer: allow non-trailers
in trailer block, 2016-10-21).

But I don’t see how either one is a subset of the other. With (i) I just
need valid trailers. With (ii) I need at least one “Git-generated”
trailer (or `(cherry picked from` I think), i.e. as soon as a
non-trailer line has infected the prospective block.

You could have respectively:

i.  Only trailers but none are configured
ii. One configured trailer and one comment line

I don’t see how one can subsume the other.

>
>> +The trailer block is by definition at the end the the message. The end
>> +of the message in turn is either (i) at the end of the input, or (ii)
>
> "at the end the the message" -> "at the end of the commit log
> message", and "the input" -> "the message", probably.

Okay, there is both a “the the” as well as missing “of”.

As to “*commit* message”: my first instinct was that the text might as
well talk about just “message” throughout, since we establish at the
beginning that a commit message is *one* application (and the main one)
but isn’t necessarily the only one (tag messages these days, in
fact). But now I see that we already use “commit message” throughout, so
it is indeed best to stick with that here.

> The latter is because not everybody is "parsing" the message to futz
> with trailers, using the message as "input", and some are "writing
> out" the message, using it as "output".

I don’t understand this part. This is supposed to be prosaic. The input
is the data on the standard input. And of that data the message is a
subset, for example and probably most notably with the
git-format-patch(1) format.

Now, we could define what “the commit message” is in terms of “the
message”. But those terms are so close, it might look like you are
restating “commit message” but just dropping “commit” because it is
clear from context now.

For comparison this is the paragraph on `master` (commit 0fae78c9).

    Existing trailers are extracted from the input by looking for
    a group of one or more lines that (i) is all trailers, or (ii) contains at
    least one Git-generated or user-configured trailer and consists of at
    least 25% trailers.
    The group must be preceded by one or more empty (or whitespace-only) lines.
    The group must either be at the end of the input or be the last
    non-whitespace lines before a line that starts with `---` (followed by a
    space or the end of the line).

>> +the last non-whitespace lines before a line that starts with `---`
>> +(followed by a space or the end of the line).
>
> OK.