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

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

From
KHKristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date
Mar 30, 2026, 22:23 UTC
Message-ID
<5ba0bbcb-25a7-4ad0-ac1d-c86508eaffdd@app.fastmail.com>
In-Reply-To
<xmqqh5px6kz4.fsf@gitster.g>
On Mon, Mar 30, 2026, at 23:55, Junio C Hamano wrote:
Show 12 quoted lines
> 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.
Show 15 quoted lines
>> 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.

Show 16 quoted lines
>
>> 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.
Show 18 quoted lines
>
>> +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!
Previous: Junio C HamanoNext: Ben Knoble
Message 11 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.