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

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

From
Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date
Jun 10, 2026, 21:21 UTC
Message-ID
<V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
In-Reply-To
<CV_doc_int-tr_key_format.533@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name (applied): kh/doc-trailers

Topic summary: Explain the format of trailer keys (alphanum and hyphens). This is important to keep in mind so that metadata is not lost to simple syntax errors. Also replace some terms and define the important ones upfront.

To that end, an overview of the changes:
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain
  the “key” format, and add a new example
• Patch 8 [new]: join some existing paragraphs that are about the same theme
  since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in
  patch 5 later in the doc
• Patch 10 [new]: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behavior
§ Changes in v3
I followed up on D. Ben’s suggestion about thematic paragraphs (patch 8).
I also made a new change as a knock-on to patch 8. That’s patch 10.
I also changed patch 11 (formerly 10): moved it out into its own section.
See the patches for details. Look for “v3” in the patch Notes.
§ Apologies for very cross-referenced commit messages
Like I wrote on v2.
    Here one thing lead to another,

And in the process I had to make changes that necessitated *other changes* as a knock-on effect. Shuffle some text, need to reshuffle three paragraphs later for consistency. And rather than piling on “While at it”/“Also”, I chose to try to make focused commits. (Which is how an idea to explain that trailer keys are alphanum/hyhens-only became eleven patches.)

But in order to follow up on related items I needed to refer to both future and previous commits. And in the process I abandoned the usual “in an upcoming commit”/“in a previous commit” in favor of perhaps a gratingly precise “commit <subject without area>”, e.g.:

    The format in its simplest form is easy to describe directly without
    comparing it to anything else; we will do that in the upcoming
    commit “explain the format after the intro”.
and,
    This also makes the introduction more consistent with how I chose
    to define trailers in the glossary:[1] “Key-value metadata”. (We will
    introduce “key–value” in the upcoming commit “explain the format after
    the intro”.)
§ Cc
(see v2)
§ In-reply-to: v1
§ Link to v2
https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/

[01/11] doc: interpret-trailers: stop fixating on RFC 822 [02/11] doc: interpret-trailers: replace “lines” with “metadata” [03/11] doc: interpret-trailers: use “metadata” in Name as well [04/11] doc: interpret-trailers: not just for commit messages [05/11] doc: interpret-trailers: explain the format after the intro [06/11] doc: interpret-trailers: explain key format [07/11] doc: interpret-trailers: add key format example [08/11] doc: interpret-trailers: join new-trailers again [09/11] doc: interpret-trailers: commit to “trailer block” term [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs [11/11] doc: interpret-trailers: document comment line treatment

 Documentation/git-interpret-trailers.adoc | 92 ++++++++++++++++-------
 1 file changed, 66 insertions(+), 26 deletions(-)
Interdiff against v2:
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index b42f957d666..d5e856f5d68 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -60,12 +60,20 @@ 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.
 
-By default, a `<key>=<value>` or `<key>:<value>` argument given
-using `--trailer` will be appended after the existing trailers only if
-the last trailer has a different (_<key>_, _<value>_) pair (or if there
-is no existing trailer). 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:
+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
@@ -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)
+is all trailers, or (ii) contains at least one Git-generated or
+user-configured trailer and consists of at
+least 25% trailers.
+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)
+the last non-whitespace lines before a line that starts with `---`
+(followed by a space or the end of the line).
+
 For convenience, a _<key-alias>_ can be configured to make using `--trailer`
 shorter to type on the command line. This can be configured using the
 `trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
@@ -87,26 +105,6 @@ 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 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.
-
-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
-least 25% trailers.
-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)
-the last non-whitespace lines before a line that starts with `---`
-(followed by a space or the end of the line).
-
-This command ignores comment lines (see `core.commentString` in
-linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
-and `commit-msg` hooks.
-
 When reading trailers, there can be no whitespace before or inside the
 _<key>_, but any number of regular space and tab characters are allowed
 between the _<key>_ and the separator. There can be whitespaces before,
@@ -119,6 +117,16 @@ key: This is a very long value, with spaces and
   newlines in it.
 ------------------------------------------------
 
+OTHER RULES
+-----------
+
+What was covered in the previous section are the rules that are relevant
+for regular use. The following points are included for completeness.
+
+This command ignores comment lines (see `core.commentString` in
+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
+and `commit-msg` hooks.
+
 OPTIONS
 -------
 `--in-place`::
Range-diff against v2:
 1:  e5d58237bc2 =  1:  e5d58237bc2 doc: interpret-trailers: stop fixating on RFC 822
 2:  5ddd39bf157 =  2:  5ddd39bf157 doc: interpret-trailers: replace “lines” with “metadata”
 3:  9f0227a1978 =  3:  9f0227a1978 doc: interpret-trailers: use “metadata” in Name as well
 4:  4cb26810d4e =  4:  4cb26810d4e doc: interpret-trailers: not just for commit messages
 5:  196c91bebe3 =  5:  196c91bebe3 doc: interpret-trailers: explain the format after the intro
 6:  688ea55599a =  6:  688ea55599a doc: interpret-trailers: explain key format
 7:  e6eafbd641f =  7:  e6eafbd641f doc: interpret-trailers: add key format example
 -:  ----------- >  8:  8849ace33e6 doc: interpret-trailers: join new-trailers again
 8:  f14d641309c !  9:  8323b84e134 doc: interpret-trailers: commit to “trailer block” term
    @@ Commit message
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-interpret-trailers.adoc ##
    -@@ Documentation/git-interpret-trailers.adoc: 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"`.
    +@@ Documentation/git-interpret-trailers.adoc: key: value
    + This means that the trimmed _<key>_ and _<value>_ will be separated by
    + "`:`{nbsp}" (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
    @@ Documentation/git-interpret-trailers.adoc: trailer.sign.key "Signed-off-by: "
     +the last non-whitespace lines before a line that starts with `---`
     +(followed by a space or the end of the line).
      
    - When reading trailers, there can be no whitespace before or inside the
    - _<key>_, but any number of regular space and tab characters are allowed
    + For convenience, a _<key-alias>_ can be configured to make using `--trailer`
    + shorter to type on the command line. This can be configured using the
 -:  ----------- > 10:  c7495c3b39e doc: interpret-trailers: rewrite new-trailers paragraphs
 9:  78125ab39f1 ! 11:  fc38e8660f0 doc: intepret-trailers: document comment line treatment
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: intepret-trailers: document comment line treatment
    +    doc: interpret-trailers: document comment line treatment
     
         Comment lines have always been ignored but this is not documented.
     
    @@ Commit message
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-interpret-trailers.adoc ##
    -@@ Documentation/git-interpret-trailers.adoc: of the message in turn is either (i) at the end of the input, or (ii)
    - the last non-whitespace lines before a line that starts with `---`
    - (followed by a space or the end of the line).
    +@@ Documentation/git-interpret-trailers.adoc: key: This is a very long value, with spaces and
    +   newlines in it.
    + ------------------------------------------------
      
    ++OTHER RULES
    ++-----------
    ++
    ++What was covered in the previous section are the rules that are relevant
    ++for regular use. The following points are included for completeness.
    ++
     +This command ignores comment lines (see `core.commentString` in
     +linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
     +and `commit-msg` hooks.
     +
    - When reading trailers, there can be no whitespace before or inside the
    - _<key>_, but any number of regular space and tab characters are allowed
    - between the _<key>_ and the separator. There can be whitespaces before,
    + OPTIONS
    + -------
    + `--in-place`::

base-commit: 5361983c075154725be47b65cca9a2421789e410
-- 
2.54.0.22.g9e26862b904
Previous: Kristoffer HaugsbakkNext: kristofferhaugsbakk@fastmail.com
Message 34 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.