git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
KHKristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date
Jun 17, 2026, 19:45 UTC
Message-ID
<729baf6b-53ea-4e8d-95ab-5935667e66c2@app.fastmail.com>
In-Reply-To
<xmqqcxxyt4op.fsf@gitster.g>
On Thu, Jun 11, 2026, at 00:24, Junio C Hamano wrote:
Show 10 quoted lines
>[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.
Show 13 quoted lines
>
>> +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.
Show 11 quoted lines
>
>>  ------------------------------------------------
>>  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).

Show 6 quoted lines
>
>> +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.
Show 6 quoted lines
>
>> +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.
Previous: Kristoffer HaugsbakkNext: Junio C Hamano
Message 54 of 90 in “git-interpret-trailers and period characters in the key”
  1. Brendan JackmanApr 1, 2025
  2. Christian CouderApr 3, 2025
  3. Junio C HamanoApr 7, 2025
  4. 0/2 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Mar 30, 2026
  5. 1/2 doc: interpret-trailers: stop fixating on RFC 822kristofferhaugsbakk@fastmail.com, Mar 30, 2026
  6. Junio C HamanoMar 30, 2026
  7. Kristoffer HaugsbakkMar 30, 2026
  8. Junio C HamanoMar 30, 2026
  9. 2/2 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Mar 30, 2026
  10. Junio C HamanoMar 30, 2026
  11. Kristoffer HaugsbakkMar 30, 2026
  12. Ben KnobleMar 31, 2026
  13. Kristoffer HaugsbakkMar 31, 2026
  14. 0/9 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Apr 13, 2026
  15. 1/9 doc: interpret-trailers: stop fixating on RFC 822kristofferhaugsbakk@fastmail.com, Apr 13, 2026
  16. 2/9 doc: interpret-trailers: replace “lines” with “metadata”kristofferhaugsbakk@fastmail.com, Apr 13, 2026
  17. 3/9 doc: interpret-trailers: use “metadata” in Name as wellkristofferhaugsbakk@fastmail.com, Apr 13, 2026
  18. 4/9 doc: interpret-trailers: not just for commit messageskristofferhaugsbakk@fastmail.com, Apr 13, 2026
  19. 5/9 doc: interpret-trailers: explain the format after the introkristofferhaugsbakk@fastmail.com, Apr 13, 2026
  20. 6/9 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Apr 13, 2026
  21. 7/9 doc: interpret-trailers: add key format examplekristofferhaugsbakk@fastmail.com, Apr 13, 2026
  22. 8/9 doc: interpret-trailers: commit to “trailer block” termkristofferhaugsbakk@fastmail.com, Apr 13, 2026
  23. 9/9 doc: intepret-trailers: document comment line treatmentkristofferhaugsbakk@fastmail.com, Apr 13, 2026
  24. Kristoffer HaugsbakkApr 13, 2026
  25. Junio C HamanoApr 13, 2026
  26. Kristoffer HaugsbakkMay 8, 2026
  27. Kristoffer HaugsbakkMay 8, 2026
  28. Junio C HamanoMay 11, 2026
  29. D. Ben KnobleMay 11, 2026
  30. Kristoffer HaugsbakkMay 24, 2026
  31. Ben KnobleMay 26, 2026
  32. Kristoffer HaugsbakkMay 26, 2026
  33. Kristoffer HaugsbakkMay 26, 2026
  34. 00/11 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  35. 01/11 doc: interpret-trailers: stop fixating on RFC 822kristofferhaugsbakk@fastmail.com, Jun 10, 2026
  36. 02/11 doc: interpret-trailers: replace “lines” with “metadata”kristofferhaugsbakk@fastmail.com, Jun 10, 2026
  37. Matt HunterJun 11, 2026
  38. Kristoffer HaugsbakkJun 16, 2026
  39. Matt HunterJun 16, 2026
  40. 03/11 doc: interpret-trailers: use “metadata” in Name as wellkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  41. 04/11 doc: interpret-trailers: not just for commit messageskristofferhaugsbakk@fastmail.com, Jun 10, 2026
  42. 05/11 doc: interpret-trailers: explain the format after the introkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  43. 06/11 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  44. 07/11 doc: interpret-trailers: add key format examplekristofferhaugsbakk@fastmail.com, Jun 10, 2026
  45. 08/11 doc: interpret-trailers: join new-trailers againkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  46. D. Ben KnobleJun 10, 2026
  47. Kristoffer HaugsbakkJun 10, 2026
  48. 09/11 doc: interpret-trailers: commit to “trailer block” termkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  49. 11/11 doc: interpret-trailers: document comment line treatmentkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  50. Junio C HamanoJun 10, 2026
  51. Junio C HamanoJun 11, 2026
  52. Kristoffer HaugsbakkJun 11, 2026
  53. Kristoffer HaugsbakkJun 11, 2026
  54. Kristoffer HaugsbakkJun 17, 2026
  55. Junio C HamanoJul 23, 2026
  56. Kristoffer HaugsbakkJul 30, 2026
  57. Kristoffer HaugsbakkAug 13, 2026
  58. 00/11 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  59. 01/11 doc: interpret-trailers: stop fixating on RFC 822kristofferhaugsbakk@fastmail.com, Jul 30, 2026
  60. 02/11 doc: interpret-trailers: replace “lines” with “metadata”kristofferhaugsbakk@fastmail.com, Jul 30, 2026
  61. 03/11 doc: interpret-trailers: use “metadata” in Name as wellkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  62. 04/11 doc: interpret-trailers: not just for commit messageskristofferhaugsbakk@fastmail.com, Jul 30, 2026
  63. 05/11 doc: interpret-trailers: explain the format after the introkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  64. 06/11 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  65. 07/11 doc: interpret-trailers: add key format examplekristofferhaugsbakk@fastmail.com, Jul 30, 2026
  66. 08/11 doc: interpret-trailers: join new-trailers againkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  67. 09/11 doc: interpret-trailers: commit to “trailer block” termkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  68. 10/11 doc: interpret-trailers: rewrite new-trailers paragraphskristofferhaugsbakk@fastmail.com, Jul 30, 2026
  69. 11/11 doc: interpret-trailers: document comment line treatmentkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  70. D. Ben KnobleAug 6, 2026
  71. Kristoffer HaugsbakkAug 8, 2026
  72. D. Ben KnobleAug 6, 2026
  73. Junio C HamanoAug 6, 2026
  74. Kristoffer HaugsbakkAug 8, 2026
  75. Kristoffer HaugsbakkAug 8, 2026
  76. 00/11 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  77. 01/11 doc: interpret-trailers: stop fixating on RFC 822kristofferhaugsbakk@fastmail.com, Aug 9, 2026
  78. 02/11 doc: interpret-trailers: replace “lines” with “metadata”kristofferhaugsbakk@fastmail.com, Aug 9, 2026
  79. 03/11 doc: interpret-trailers: use “metadata” in Name as wellkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  80. 04/11 doc: interpret-trailers: not just for commit messageskristofferhaugsbakk@fastmail.com, Aug 9, 2026
  81. 05/11 doc: interpret-trailers: explain the format after the introkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  82. 06/11 doc: interpret-trailers: explain key formatkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  83. 07/11 doc: interpret-trailers: add key format examplekristofferhaugsbakk@fastmail.com, Aug 9, 2026
  84. 08/11 doc: interpret-trailers: join new-trailers againkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  85. 09/11 doc: interpret-trailers: commit to “trailer block” termkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  86. 10/11 doc: interpret-trailers: rewrite new-trailers paragraphskristofferhaugsbakk@fastmail.com, Aug 9, 2026
  87. 11/11 doc: interpret-trailers: document comment line treatmentkristofferhaugsbakk@fastmail.com, Aug 9, 2026
  88. Ben KnobleAug 10, 2026
  89. Kristoffer HaugsbakkAug 10, 2026
  90. Junio C HamanoAug 10, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.