{"thread":{"id":"63233","subject":"git-interpret-trailers and period characters in the key","startedAt":"2025-04-01T13:27:38Z","lastAt":"2026-08-13T17:44:08Z","messageCount":90,"participants":["Brendan Jackman","Christian Couder","Junio C Hamano","kristofferhaugsbakk@fastmail.com","Kristoffer Haugsbakk","Ben Knoble","D. Ben Knoble","Matt Hunter"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"515432","messageId":"CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com","threadId":"63233","inReplyTo":null,"subject":"git-interpret-trailers and period characters in the key","fromName":"Brendan Jackman","fromEmail":"jackmanb@google.com","sentAt":"2025-04-01T13:27:26Z","receivedAt":"2025-04-01T13:27:38Z","isPatch":false,"body":"Hi folks,\n\nJust debugging one of my scripts and I found that\ngit-interpret-trailers behaves surprisingly on trailer keys containing\n'.' characters:\n\n❯❯ cat commit.txt\nmy commit title\n\nMy-Footer: foo\n\n❯❯ git interpret-trailers --parse commit.txt\nMy-Footer: foo\n\n❯❯ cat commit2.txt\nmy commit title\n\nMy-Footer: foo\nMy-6.11-Version: bar\n\n❯❯ git interpret-trailers --parse commit.txt\n\nBasically, as soon as any trailer key contains a period (which in my\ncase, it does because the trailer keys refer to versions of of\nsoftware, i.e. \"this commit was backported from the following Linux\nkernel commit which appeared in version 6.1\"), it stops parsing the\ntrailer block.\n\nMy guess is that this is just that it doesn't allow periods in the\ntrailer key, and once there's one line in the block that isn't a\ntrailer, it no longer meets the requirements described in the man\npage.\n\nI can't find anything in the man page about why the period character\nshould break this. Am I missing anything there?\n\nCheers,\nBrendan\n\n❯❯ git --version\ngit version 2.49.0.472.ge94155a9ec-goog\n\n(IIUC that -goog in the version string is just noting that we have\nmonitoring logic added to our internal Git built to spot people\nleaking IP, there's no actual feature customisation)\n"},{"id":"515580","messageId":"CAP8UFD0SxKOYFegN=DnmyY5RW7dMqyohGzeCfoVLNOtwjY2APA@mail.gmail.com","threadId":"63233","inReplyTo":"CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com","subject":"Re: git-interpret-trailers and period characters in the key","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2025-04-03T11:07:27Z","receivedAt":"2025-04-03T11:07:41Z","isPatch":false,"body":"Hi,\n\nOn Tue, Apr 1, 2025 at 3:27 PM Brendan Jackman wrote:\n\n> Basically, as soon as any trailer key contains a period (which in my\n> case, it does because the trailer keys refer to versions of of\n> software, i.e. \"this commit was backported from the following Linux\n> kernel commit which appeared in version 6.1\"), it stops parsing the\n> trailer block.\n>\n> My guess is that this is just that it doesn't allow periods in the\n> trailer key, and once there's one line in the block that isn't a\n> trailer, it no longer meets the requirements described in the man\n> page.\n\nYeah, it's also my guess that the trailer block is not considered a\ntrailer block anymore as your trailer key is not considered a valid\ntrailer key.\n\n> I can't find anything in the man page about why the period character\n> should break this. Am I missing anything there?\n\nWe tried to be quite strict when implementing trailers to avoid\nregular text to be too easily considered trailers.\n\nHaving a config option or something to be a bit more lenient and\naccept more characters in trailer keys could help some people, and it\nmight not be very difficult to implement. On the other hand if people\nstart to have a lot of weird trailers around, and abuse the config\noption to make it too lenient, then it could be a bad thing in general\nas more and more regular text might be interpreted as trailers.\n\nI also agree that our doc about this could be improved. Patches welcome.\n\nBest,\nChristian.\n"},{"id":"515801","messageId":"xmqqa58rn1ww.fsf@gitster.g","threadId":"63233","inReplyTo":"CAP8UFD0SxKOYFegN=DnmyY5RW7dMqyohGzeCfoVLNOtwjY2APA@mail.gmail.com","subject":"Re: git-interpret-trailers and period characters in the key","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-07T20:37:35Z","receivedAt":"2025-04-07T20:37:37Z","isPatch":false,"body":"Christian Couder writes:\n\n> Having a config option or something to be a bit more lenient and\n> accept more characters in trailer keys could help some people, and it\n> might not be very difficult to implement. On the other hand if people\n> start to have a lot of weird trailers around, and abuse the config\n> option to make it too lenient, then it could be a bad thing in general\n> as more and more regular text might be interpreted as trailers.\n>\n> I also agree that our doc about this could be improved. Patches welcome.\n\nThanks for a concise summary. \n\nI agree that loosening the rule, or even adding an option to loosen\nthe rule, is detrimental to the ecosystem at large, and\ndocumentation can be improved.\n\nIn retrospect, I supsect that it even was a mistake to special case\nthe #BUGID syntax when the trailer was pretty much about lines that\nlook similar to E-Mail-Header: fields. Let's not make it worse.\n\nThanks.\n"},{"id":"540428","messageId":"CV_doc_int-tr_key_format.533@msgid.xyz","threadId":"63233","inReplyTo":"CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com","subject":"[PATCH 0/2] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-30T21:11:31Z","receivedAt":"2026-03-30T21:11:53Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name: doc-int-tr-2-key-format\n\nTopic summary: Explain the format of trailer keys (alphanum and\nhyphens). This is important to keep in mind so that metadata is not lost to\nsimple syntax errors.\n\nTo facilitate this there is a first commit/patch to reorient the\nintroduction towards discussing “key-value pairs”, since that makes it\neasier to follow up with an explanation of the *key* format.\n\n§ Cc\n\nLinus Arver as the author of the example that this change touches.\n\n[1/2] doc: interpret-trailers: stop fixating on RFC 822\n[2/2] doc: interpret-trailers: explain key format\n\n Documentation/git-interpret-trailers.adoc | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\n\nbase-commit: 5361983c075154725be47b65cca9a2421789e410\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"540429","messageId":"doc_int-tr_key_format.534@msgid.xyz","threadId":"63233","inReplyTo":"CV_doc_int-tr_key_format.533@msgid.xyz","subject":"[PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-30T21:11:32Z","receivedAt":"2026-03-30T21:12:13Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command handles the *trailers* key–value pair format. But the\ncommand isn’t introduced as such; it is instead introduced by stating\nthat these trailer lines look similar to RFC 822 email headers.\n\nThis is overwrought:\n\n• most people do not deal directly with email headers or think about\n email RFCs; and\n• simply calling them “key-value pairs” should be more than suggestive\n enough considering the context here.\n\nSe let’s call the format just that, show the example, and then briefly\nexplain the format of the keys (coming up); this change facilitates\nthe next commit where we will explain what characters are permitted in\nthe key.\n\nConcretely, let’s replace the introduction with “key-value pairs” and\nremove the last mention of RFC 822, but keep the innocuous comparison\nwith email line folding in the middle. We do not need the final\ndisclaimer now that the *only* mention of email headers is that Git\ntrailers have something similar to email line folding; there is no\ninvitation to speculate that trailers would follow any other email\nformat rules since we do not compare them directly any more.\n\n❦\n\nTalking about trailers as an RFC 822/2822-like format seems to go back\nto the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated\nthis command and in turn the first trailer support in git(1) beyond\nadding s-o-b lines.\n\n† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n The (❦) is meant as a thematic break. There is too much of a thematic jump\n between these two paragraphs without a section or something else breaking\n them up.\n \n (one was not tempted to use `---` here)\n\n Documentation/git-interpret-trailers.adoc | 9 +++------\n 1 file changed, 3 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 77b4f63b05c..e7c1f821619 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n-headers, at the end of the otherwise free-form part of a commit\n-message. For example, in the following commit message\n+Add or parse _trailer_ key-value pairs at the end of the otherwise\n+free-form part of a commit message. For example, in the following commit\n+message\n \n ------------------------------------------------\n subject\n@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n-Note that trailers do not follow (nor are they intended to follow) many of the\n-rules for RFC 822 headers. For example they do not follow the encoding rule.\n-\n OPTIONS\n -------\n `--in-place`::\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"540430","messageId":"doc_int-tr_not_rfc.535@msgid.xyz","threadId":"63233","inReplyTo":"CV_doc_int-tr_key_format.533@msgid.xyz","subject":"[PATCH 2/2] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-30T21:11:33Z","receivedAt":"2026-03-30T21:12:32Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nA trailer key must consist of ASCII alphanumeric characters and\nhyphens *only*. Let’s document it explicitly instead of relying on\nreaders being conservative and painting their trailers by numbers\n(by the documentation examples).\n\nThe previous commit for “key–value pairs” allows us to segue right into\ndescribing these lines as consisting of a key and a value, which is our\nopening to describing the key format.\n\nJust like *trailer* we emphasize these two first standalone word\nmentions. They are then mostly used in placeholders throughout the rest\nof the document ( and ).\n\nReported-by: Brendan Jackman \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n `trailer.c` uses `isalnum()`. That short research together with a little\n testing left me with this conclusion. (The C unit tests for trailers and\n t7513-interpret-trailers.sh seem to just use lines with spaces and no\n separators for non-trailer lines.)\n\n Documentation/git-interpret-trailers.adoc | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex e7c1f821619..92d9c95f9d2 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -27,7 +27,10 @@ Signed-off-by: Alice \n Signed-off-by: Bob \n ------------------------------------------------\n \n-the last two lines starting with `Signed-off-by` are trailers.\n+the last two lines starting with `Signed-off-by` are trailers. These two\n+trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).\n+The key must consist of only ASCII alphanumeric characters and hyphens\n+(`-`). The hyphens serve as interword separators.\n \n This command reads commit messages from either the\n __ arguments or the standard input if no __ is specified.\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"540432","messageId":"xmqqh5px6kz4.fsf@gitster.g","threadId":"63233","inReplyTo":"doc_int-tr_not_rfc.535@msgid.xyz","subject":"Re: [PATCH 2/2] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-30T21:55:27Z","receivedAt":"2026-03-30T21:55:29Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> A trailer key must consist of ASCII alphanumeric characters and\n> hyphens *only*. Let’s document it explicitly instead of relying on\n> readers being conservative and painting their trailers by numbers\n> (by the documentation examples).\n\n\"paint\"? I am not sure what the latter half of the above paragraph\nwants to say, even though I do agree that being explicit about the\nallowed characters is a good idea.\n\n> The previous commit for “key–value pairs” allows us to segue right into\n> describing these lines as consisting of a key and a value, which is our\n> opening to describing the key format.\n\nAnd it is a good place to remedy the issue I raised for the previous\nstep as well ;-)\n\n> Just like *trailer* we emphasize these two first standalone word\n> mentions.\n\nAgain, I have no idea what \"these two first standalone word\" wants\nto refer to. It is not even clear to me if it refers to a single\nthing, or two things---the verb \"mentions\" hints that the subject of\nthe sentence must be plural, but I cannot tell what two things you\nare referring to.\n\n> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n> index e7c1f821619..92d9c95f9d2 100644\n> --- a/Documentation/git-interpret-trailers.adoc\n> +++ b/Documentation/git-interpret-trailers.adoc\n> @@ -27,7 +27,10 @@ Signed-off-by: Alice \n> Signed-off-by: Bob \n> ------------------------------------------------\n> \n> -the last two lines starting with `Signed-off-by` are trailers.\n> +the last two lines starting with `Signed-off-by` are trailers. These two\n> +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).\n\nRemedy the loss of \"e-mail like\" by ending the above sentence more like:\n\n ... and Bob), with a colon appended at the end of the key.\n\n> +The key must consist of only ASCII alphanumeric characters and hyphens\n> +(`-`). The hyphens serve as interword separators.\n\nThe first sentence is a very much welcome addition. I however doubt\nthat the last sentence is necessary or beneficial, as \"SignedOffBy\"\nis a perfectly fine key to be used for a trailer if a project\nprefers (not this project, though). I would not object to\n\n The hyphens can be used as inter-word separators.\n\nor\n\n The hyphens can be used as inter-word separators, if you want.\n\nbut any expression that can be misinterpreted that the document\nstrongly suggests projects and communities to adopt the \"hyphen as\ninter-word separator\" convention is not very welcome.\n\nThanks.\n"},{"id":"540433","messageId":"5ba0bbcb-25a7-4ad0-ac1d-c86508eaffdd@app.fastmail.com","threadId":"63233","inReplyTo":"xmqqh5px6kz4.fsf@gitster.g","subject":"Re: [PATCH 2/2] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-30T22:23:19Z","receivedAt":"2026-03-30T22:23:41Z","isPatch":true,"body":"On Mon, Mar 30, 2026, at 23:55, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> From: Kristoffer Haugsbakk \n>>\n>> A trailer key must consist of ASCII alphanumeric characters and\n>> hyphens *only*. Let’s document it explicitly instead of relying on\n>> readers being conservative and painting their trailers by numbers\n>> (by the documentation examples).\n>\n> \"paint\"? I am not sure what the latter half of the above paragraph\n> wants to say, even though I do agree that being explicit about the\n> allowed characters is a good idea.\n\n“Paint by numbers”, “paint inside the lines.” Using the docs as a guide\nto create very similar-looking keys. Contrast with the original issue\nhere:\n\n Basically, as soon as any trailer key contains a period (which in my\n case, it does because the trailer keys refer to versions of of\n software, i.e. \"this commit was backported from the following Linux\n kernel commit which appeared in version 6.1\"), [...]\n\nA symptom of taking the examples from the doc and adding just a little\nextra to it.\n\nThis cutesy phrasing can be dropped. We’ll see.\n\n>> The previous commit for “key–value pairs” allows us to segue right into\n>> describing these lines as consisting of a key and a value, which is our\n>> opening to describing the key format.\n>\n> And it is a good place to remedy the issue I raised for the previous\n> step as well ;-)\n>\n>> Just like *trailer* we emphasize these two first standalone word\n>> mentions.\n>\n> Again, I have no idea what \"these two first standalone word\" wants\n> to refer to. It is not even clear to me if it refers to a single\n> thing, or two things---the verb \"mentions\" hints that the subject of\n> the sentence must be plural, but I cannot tell what two things you\n> are referring to.\n\nKey & value.\n\nSomething like:\n\n Just like *trailer* we emphasize these two first standalone word\n mentions (key and value).\n\nThey are the only emphasized words in the diff. Although I *have* relied\ntoo much on the diff context before.\n\n>\n>> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n>> index e7c1f821619..92d9c95f9d2 100644\n>> --- a/Documentation/git-interpret-trailers.adoc\n>> +++ b/Documentation/git-interpret-trailers.adoc\n>> @@ -27,7 +27,10 @@ Signed-off-by: Alice \n>> Signed-off-by: Bob \n>> ------------------------------------------------\n>>\n>> -the last two lines starting with `Signed-off-by` are trailers.\n>> +the last two lines starting with `Signed-off-by` are trailers. These two\n>> +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).\n>\n> Remedy the loss of \"e-mail like\" by ending the above sentence more like:\n>\n> ... and Bob), with a colon appended at the end of the key.\n\nOkay. I’ll try with:\n\n ... and Bob), with a colon separating the key and the value.\n\n>\n>> +The key must consist of only ASCII alphanumeric characters and hyphens\n>> +(`-`). The hyphens serve as interword separators.\n>\n> The first sentence is a very much welcome addition. I however doubt\n> that the last sentence is necessary or beneficial, as \"SignedOffBy\"\n> is a perfectly fine key to be used for a trailer if a project\n> prefers (not this project, though). I would not object to\n>\n> The hyphens can be used as inter-word separators.\n>\n> or\n>\n> The hyphens can be used as inter-word separators, if you want.\n>\n> but any expression that can be misinterpreted that the document\n> strongly suggests projects and communities to adopt the \"hyphen as\n> inter-word separator\" convention is not very welcome.\n\nI’ll take the first one here.\n\nThank you!\n"},{"id":"540434","messageId":"xmqqbjg56jhb.fsf@gitster.g","threadId":"63233","inReplyTo":"doc_int-tr_key_format.534@msgid.xyz","subject":"Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-30T22:27:44Z","receivedAt":"2026-03-30T22:27:47Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> Notes (series):\n> The (❦) is meant as a thematic break. There is too much of a thematic jump\n> between these two paragraphs without a section or something else breaking\n> them up.\n\nI do not quite agree with this particular instance. It rather looks\nmore like an unnecessary hostile move against folks who prefer to\nsee plain ASCII on their screen unless absolutely needed (like say\nfor displaying people's names with letters outside US-ASCII), as the\ntwo paragraphs before and after are not all that unrelated.\n\nOne thing that I found a bit wanting after this step is that it lost\nhint that the primary way to delimit between the key and value in\nthe trailer lines is to have a colon immediately after key and with\na single whitespace before the value, which is what is very typical\nto see in the e-mail headers. Sure, if a reader has not heard of\n(2)822, hinting that these resemble e-mail headers would not help\nthem at all, but those of us among the audience of this document who\nhave seen e-mail headers and how they feel, the \"look similar to\"\nwas enough to hint how a colon is typically used in a trailer. In\nthe updated text, the readers will have to way around line #65\nbefore seeing the official \"both key and value are trimmed for\nwhitespaces on both ends and then made into 'key: value'\".\n\nI mentioned \"issues I raised on the previous step\" in my review on\n2/2, but did not remember that I haven't sent out this one yet ;-)\n\n> @@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]\n> \n> DESCRIPTION\n> -----------\n> -Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n> -headers, at the end of the otherwise free-form part of a commit\n> -message. For example, in the following commit message\n> +Add or parse _trailer_ key-value pairs at the end of the otherwise\n> +free-form part of a commit message. For example, in the following commit\n> +message\n> \n> ------------------------------------------------\n> subject\n"},{"id":"540439","messageId":"2ed992d8-7314-423d-828a-5801f4de2471@app.fastmail.com","threadId":"63233","inReplyTo":"xmqqbjg56jhb.fsf@gitster.g","subject":"Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-30T22:56:44Z","receivedAt":"2026-03-30T22:57:06Z","isPatch":true,"body":"On Tue, Mar 31, 2026, at 00:27, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> Notes (series):\n>> The (❦) is meant as a thematic break. There is too much of a thematic jump\n>> between these two paragraphs without a section or something else breaking\n>> them up.\n>\n> I do not quite agree with this particular instance. It rather looks\n> more like an unnecessary hostile move against folks who prefer to\n> see plain ASCII on their screen unless absolutely needed (like say\n> for displaying people's names with letters outside US-ASCII)\n\nWe can use `***` instead.\n\n>, as the two paragraphs before and after are not all that unrelated.\n\nOr nothing.\n\n> One thing that I found a bit wanting after this step is that it lost\n> hint that the primary way to delimit between the key and value in\n> the trailer lines is to have a colon immediately after key and with\n> a single whitespace before the value, which is what is very typical\n> to see in the e-mail headers. Sure, if a reader has not heard of\n> (2)822, hinting that these resemble e-mail headers would not help\n> them at all, but those of us among the audience of this document who\n> have seen e-mail headers and how they feel, the \"look similar to\"\n> was enough to hint how a colon is typically used in a trailer. In\n> the updated text, the readers will have to way around line #65\n> before seeing the official \"both key and value are trimmed for\n> whitespaces on both ends and then made into 'key: value'\".\n>\n> I mentioned \"issues I raised on the previous step\" in my review on\n> 2/2, but did not remember that I haven't sent out this one yet ;-)\n\nOkay. See my previous email about adding the “separated by” part.\n\nI only mentioned the colon there (prev. email). Not the space. The\nreason is the same as what I wrote in the commit message. We say that\nthese are key–value pairs and only use `:`SP in all the examples. I\nthink just pointing out the colon at the start is enough detail at that\npoint before all the details reveal themselves near the end of the\nDescription section.\n\nIMO it’s best to stick to the normalized `:`SP when writing as well,\neven though you can write `:` without any whitespace. But I can’t\nimagine readers being motivated to try to deviate from the normalized\nseparator form; the doc just uses `:`SP... so why not just use that as\nwell? Compare with the key format: people *will* (or have) tried with\ndots/periods, maybe also Unicode like\n\n Skapad-på: feature-branch-something\n\n... because that has some data content (not just syntactic variation as\nis the case for the separator format).\n\n>[snip]\n"},{"id":"540445","messageId":"xmqqmrzo6gur.fsf@gitster.g","threadId":"63233","inReplyTo":"2ed992d8-7314-423d-828a-5801f4de2471@app.fastmail.com","subject":"Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-30T23:24:28Z","receivedAt":"2026-03-30T23:24:31Z","isPatch":true,"body":"\"Kristoffer Haugsbakk\" writes:\n\n> IMO it’s best to stick to the normalized `:`SP when writing as well,\n\nAbsolutely. That is why I suggested to mention colon somewhere when\nwe talk about key and value. Your 2/2 with minor fixes you alluded\nto in your review response made the worry I raised for 1/2 go away.\n\nThanks.\n\n"},{"id":"540516","messageId":"8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com","threadId":"63233","inReplyTo":"5ba0bbcb-25a7-4ad0-ac1d-c86508eaffdd@app.fastmail.com","subject":"Re: [PATCH 2/2] doc: interpret-trailers: explain key format","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-03-31T12:35:49Z","receivedAt":"2026-03-31T12:36:01Z","isPatch":true,"body":"\n\n> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk a écrit :\n> \n> On Mon, Mar 30, 2026, at 23:55, Junio C Hamano wrote:\n>> kristofferhaugsbakk@fastmail.com writes:\n>> \n>>> Just like *trailer* we emphasize these two first standalone word\n>>> mentions.\n>> \n>> Again, I have no idea what \"these two first standalone word\" wants\n>> to refer to. It is not even clear to me if it refers to a single\n>> thing, or two things---the verb \"mentions\" hints that the subject of\n>> the sentence must be plural, but I cannot tell what two things you\n>> are referring to.\n> \n> Key & value.\n> \n> Something like:\n> \n> Just like *trailer* we emphasize these two first standalone word\n> mentions (key and value).\n> \n> They are the only emphasized words in the diff. Although I *have* relied\n> too much on the diff context before.\n\nPerhaps “we emphasize the introduction of the terms ‘key’ and ‘value’” (much like a technical manual or paper may emphasize the first use of a new word or abbreviation, making subsequent uses link to it so readers can find the definition)?\n\nI do find it interesting that the introduction is with an example rather than a definition. This suits “learning order” (concrete->abstract), but not necessarily “reference order” (where I just want to get to the definition). Hm.\n\nI’m not sure I have any concrete suggestions, though."},{"id":"540531","messageId":"660b739f-a738-4359-92bd-cb24f5bcd624@app.fastmail.com","threadId":"63233","inReplyTo":"8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com","subject":"Re: [PATCH 2/2] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-31T16:03:46Z","receivedAt":"2026-03-31T16:04:07Z","isPatch":true,"body":"On Tue, Mar 31, 2026, at 14:35, Ben Knoble wrote:\n>> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk a écrit :\n>>>[snip]\n>>\n>> Key & value.\n>>\n>> Something like:\n>>\n>> Just like *trailer* we emphasize these two first standalone word\n>> mentions (key and value).\n>>\n>> They are the only emphasized words in the diff. Although I *have* relied\n>> too much on the diff context before.\n>\n> Perhaps “we emphasize the introduction of the terms ‘key’ and ‘value’”\n> (much like a technical manual or paper may emphasize the first use of a\n> new word or abbreviation, making subsequent uses link to it so readers\n> can find the definition)?\n\nI think I’ll steal that. Thanks!\n\n> I do find it interesting that the introduction is with an example\n> rather than a definition.\n\nThe example is from Linus Arver in d57fa7fc (doc: trailer: add more\nexamples in DESCRIPTION, 2023-06-15).[1] The version before that[2]\nindirectly showed a `token: value` example (“will appear in the output\nlike”) after five paragraphs.\n\n† 1: One review comment: https://lore.kernel.org/git/xmqqmt2emwlj.fsf@gitster.g/\n† 2: `git show d57fa7fc73202af226b6c0^1:Documentation/git-interpret-trailers.txt`\n\n> This suits “learning order” (concrete->abstract), but not necessarily\n> “reference order” (where I just want to get to the definition). Hm.\n>\n> I’m not sure I have any concrete suggestions, though.\n\nI think the only practical starting point for this format is the\nsimplest case first, namely:\n\n1. One line per trailer (c.f. the value takes up multiple lines)\n2. Non-empty values (see `--trim-empty`)\n3. Default separator\n4. No non-trailer lines\n5. No configuration\n\nCurrently that starts off with two examples. But let’s try the other\nway around:\n\n***\n\nA _trailer_ in its simplest form is a key-value pair with a colon as a\nseparator. The _key_ consists of ASCII alphanumeric characters and\nhyphens (`-`). A _trailer block_ consists of one or more such\ntrailers. The trailer block needs to be preceded by a blank\nline.[**1**] In other words:\n\n \n\n : \n\nWhere consists of ASCII alphanumeric characters and hyphens. For\nexample:\n\n[we’re back to the original example]\n------------------------------------------------\nsubject\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit.\n\nSigned-off-by: Alice \nSigned-off-by: Bob \n------------------------------------------------\n\n***\n\nAlso optionally interject some words about commit messages and whatnot\n(or even tag messages for that matter, now).\n\nI was originally feeling skeptical of changing to something like\nreference-first. But I like this now that I have gone through the\nexercise of trying it out. So thanks for mentioning it. ;)\n\n[**1**]: git-commit(1) stripspace behavior etc. doesn’t make this\n obvious but you can have just a blank line and then a trailer block. You\n don’t need any text before the blank line. `LF` indicates the blank\n line:\n\n LF\n Signed-off-by: Me\n"},{"id":"541465","messageId":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","threadId":"63233","inReplyTo":"CV_doc_int-tr_key_format.533@msgid.xyz","subject":"[PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:20:59Z","receivedAt":"2026-04-13T10:21:30Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-trailers\n\nTopic summary: Explain the format of trailer keys (alphanum and\nhyphens). This is important to keep in mind so that metadata is not\nlost to simple syntax errors. Also replace some terms and define the\nimportant ones upfront.\n\nTo that end, an overview of the changes:\n\n• Patches 1–3: remove RFC 822 mentions, “metadata” term\n• Patch 4: This command is not just for commit messages\n• Patches 5–7: Explain the format in the simplest case, explain\n the “key” format, and add a new example\n• Patch 8: Also use the “trailer block” term introduced to the doc in\n patch 5 later in the doc\n• Patch 9: document line comment behavior\n\n§ Changes in v2\n\nHere one thing lead to another, mostly because changing one part of\nthe doc necessitated knock-on changes. An exception though is\nthe last patch which could be added later/separately.\n\nAs for the changes requested after the review on v1:\n\n• Add missing mention of the default separator (:)\n• Remove confusing “paint by numbers” reference\n• Remove “The hyphens serve as interword separators”. This is a normative\n statement.\n\n An advisory statement would have been fine. But I see now that I didn’t\n weave that in to this version.\n• There was an unclear part:\n\n we emphasize these two first standalone word mentions.\n\n Which shouldn’t be a problem now that the context/patch has been\n rewritten.\n\n§ Cc\n\nLinus Arver as the author of the example that this change touches.\n\nThis was more relevant on v1.\n\n§ Link to v1\n\nhttps://lore.kernel.org/git/CV_doc_int-tr_key_format.533@msgid.xyz/#t\n\n[1/9] doc: interpret-trailers: stop fixating on RFC 822\n[2/9] doc: interpret-trailers: replace “lines” with “metadata”\n[3/9] doc: interpret-trailers: use “metadata” in Name as well\n[4/9] doc: interpret-trailers: not just for commit messages\n[5/9] doc: interpret-trailers: explain the format after the intro\n[6/9] doc: interpret-trailers: explain key format\n[7/9] doc: interpret-trailers: add key format example\n[8/9] doc: interpret-trailers: commit to “trailer block” term\n[9/9] doc: intepret-trailers: document comment line treatment\n\n Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++------\n 1 file changed, 50 insertions(+), 18 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 92d9c95f9d2..b42f957d666 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -3,7 +3,7 @@ git-interpret-trailers(1)\n \n NAME\n ----\n-git-interpret-trailers - Add or parse structured information in commit messages\n+git-interpret-trailers - Add or parse metadata in commit messages\n \n SYNOPSIS\n --------\n@@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ key-value pairs at the end of the otherwise\n-free-form part of a commit message. For example, in the following commit\n-message\n+Add or parse trailers metadata at the end of the otherwise\n+free-form part of a commit message, or any other kind of text.\n+\n+A _trailer_ in its simplest form is a key-value pair with a colon as a\n+separator. The _key_ consists of ASCII alphanumeric characters and\n+hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n+trailer block needs to be preceded by a blank line, where a _blank line_\n+is either an empty or a whitespace-only line. For example, in the\n+following commit message\n \n ------------------------------------------------\n subject\n@@ -27,10 +33,7 @@ Signed-off-by: Alice \n Signed-off-by: Bob \n ------------------------------------------------\n \n-the last two lines starting with `Signed-off-by` are trailers. These two\n-trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).\n-The key must consist of only ASCII alphanumeric characters and hyphens\n-(`-`). The hyphens serve as interword separators.\n+the last two lines starting with `Signed-off-by` are trailers.\n \n This command reads commit messages from either the\n __ arguments or the standard input if no __ is specified.\n@@ -84,19 +87,25 @@ trailer.sign.key \"Signed-off-by: \"\n in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n \n-By default the new trailer will appear at the end of all the existing\n-trailers. If there is no existing trailer, the new trailer will appear\n-at the end of the input. A blank line will be added before the new\n-trailer if there isn't one already.\n+By default the new trailer will appear at the end of the trailer block.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line (specifically an empty line)\n+will be inserted before the new trailer block in that case.\n \n-Existing trailers are extracted from the input by looking for\n-a group of one or more lines that (i) is all trailers, or (ii) contains at\n-least one Git-generated or user-configured trailer and consists of at\n+Existing trailers are extracted from the input by looking for the\n+trailer block. Concretely, that is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n least 25% trailers.\n-The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the input or be the last\n-non-whitespace lines before a line that starts with `---` (followed by a\n-space or the end of the line).\n+The trailer block is by definition at the end the the message. The end\n+of the message in turn is either (i) at the end of the input, or (ii)\n+the last non-whitespace lines before a line that starts with `---`\n+(followed by a space or the end of the line).\n+\n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n \n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n@@ -402,6 +411,29 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n+* Here we try to to use three different trailer keys. But it fails\n+ because two of them are not recognized as trailer keys.\n++\n+----\n+$ cat msg.txt\n+subject\n+\n+Skapad-på: some-branch\n+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n+Reviewed-by: Alice \n+$ git interpret-trailers --only-trailers \n\nThis command handles the trailers metadata format. But the command\nisn’t introduced as such; it is instead introduced by stating that\nthese trailer lines look similar to RFC 822 email headers.\n\nThis is overwrought; most people do not deal directly with email\nheaders, and certainly not email RFCs.\n\nTrailers are just key–value pairs that, like email headers, use colon\nas the separator. The format in its simplest form is easy to describe\ndirectly without comparing it to anything else; we will do that in the\nupcoming commit “explain the format after the intro”.\n\nFor now, let’s:\n\n• remove the first mention of email headers;\n• keep the second, innocuous comparison with email line folding in the\n middle; and\n• remove the now-unneeded disclaimer that trailers do not share many of\n the features of RFC 822 email headers—there is no invitation to\n speculate that trailers would follow any other email format rules\n since we do not compare them directly any more.\n\n***\n\nTalking about trailers as an RFC 822/2822-like format seems to go back\nto the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated\nthis command and in turn the first trailer support in git(1) beyond\nadding s-o-b lines.\n\n† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Use `***` as a thematic break instead of `❦`\n • Change to “metadata” instead of “key–value pairs” since this series\n version adds a paragraph after this one where we dig into this\n term. And “metadata” describes the purpose of this format.\n\n Documentation/git-interpret-trailers.adoc | 9 +++------\n 1 file changed, 3 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 77b4f63b05c..1878848ad2a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n-headers, at the end of the otherwise free-form part of a commit\n-message. For example, in the following commit message\n+Add or parse _trailer_ lines at the end of the otherwise\n+free-form part of a commit message. For example, in the following commit\n+message\n \n ------------------------------------------------\n subject\n@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n-Note that trailers do not follow (nor are they intended to follow) many of the\n-rules for RFC 822 headers. For example they do not follow the encoding rule.\n-\n OPTIONS\n -------\n `--in-place`::\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541467","messageId":"V2_metadata_not_lines.615@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 2/9] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:01Z","receivedAt":"2026-04-13T10:22:07Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe removed the initial comparison to email headers in the previous\ncommit. Now the introduction paragraph just says “trailer lines”, and\nthe only hint that this is metadata/structured information is the\n“otherwise free-form” phrase.\n\nLet’s replace “lines” with “metadata” since that is their purpose.\nThis also makes the introduction more consistent with how I chose\nto define trailers in the glossary:[1] “Key-value metadata”. (We will\nintroduce “key–value” in the upcoming commit “explain the format after\nthe intro”.)\n\n† 1: 68e3c69e (Documentation/glossary: describe \"trailer\", 2024-11-17)\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 1878848ad2a..3f60fd9b720 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines at the end of the otherwise\n+Add or parse trailers metadata at the end of the otherwise\n free-form part of a commit message. For example, in the following commit\n message\n \n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541468","messageId":"V2_metadata_Name_section.616@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 3/9] doc: interpret-trailers: use “metadata” in Name as well","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:02Z","receivedAt":"2026-04-13T10:22:26Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe now since the previous commit introduce the format as “trailers\nmetadata”. We can replace “structured information” with “metadata”\nin the “Name” section to be consistent.\n\nWhile “structured information” does emphasize that the data is not\nloosely structured, we also say that this command adds to or parses\nthis format. I don’t think that we need to emphasize that it is\nstructured since clearly there is some structure there.\n\nBoth “metadata” and “structured information” can convey the same\ninformation. But “metadata” is shorter and easier to deploy since\nit’s just one word.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 3f60fd9b720..4e92c8299bb 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -3,7 +3,7 @@ git-interpret-trailers(1)\n \n NAME\n ----\n-git-interpret-trailers - Add or parse structured information in commit messages\n+git-interpret-trailers - Add or parse metadata in commit messages\n \n SYNOPSIS\n --------\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541469","messageId":"V2_cmt_msg_or_other_texts.617@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 4/9] doc: interpret-trailers: not just for commit messages","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:03Z","receivedAt":"2026-04-13T10:22:45Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command doesn’t interface with commits directly. You can\ninterpret or modify any kind of text, even though commit messages\nare the most relevant.\n\nThe git(1) suite also isn’t restricted to only direct commit support\nsince git-tag(1) learned `--trailer` in 066cef77 (builtin/tag: add\n--trailer option, 2024-05-05)\n\nNow, we already introduce the command in the “Name” section as dealing\nwith commit messages as well. That is fine since that intro line needs\nto remain pretty short.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 4e92c8299bb..7329e710e1a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty]\n DESCRIPTION\n -----------\n Add or parse trailers metadata at the end of the otherwise\n-free-form part of a commit message. For example, in the following commit\n-message\n+free-form part of a commit message, or any other kind of text.\n+For example, in the following commit message\n \n ------------------------------------------------\n subject\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541470","messageId":"V2_trailer_explain_format.618@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 5/9] doc: interpret-trailers: explain the format after the intro","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:04Z","receivedAt":"2026-04-13T10:23:04Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nYou need to read the entire “Description” section in order to understand\nthe full trailer format. But there are many nuances, so that’s fine.\nAs a starter though we have an introductory example.[1] That turns out\nto be crucial; the rest of this section talks about the mechanics of the\ncommand and only incidentally the format itself.\n\nNow, although the example might arguably be self-explanatory, we can\nadd a little preamble which defines the format in its simplest form as\nwell as define the most important terms.\n\nNote that we name the “blank line” rule since I want to use that term\nevery time it comes up. It gets very mildly obfuscated if you call it a\n“blank line” in one place[2] and “empty (or whitespace-only) ...” in\nanother one.[3]\n\nWe will define the format of the *key* in the next commit.\n\n† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,\n 2023-06-15)\n† 2: `Documentation/git-interpret-trailers.adoc:86` in\n 5361983c (The 22nd batch, 2026-03-27)\n† 3: `Documentation/git-interpret-trailers.adoc:93` in\n 5361983c (The 22nd batch, 2026-03-27)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 7329e710e1a..bcd79b19bd7 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -16,7 +16,12 @@ DESCRIPTION\n -----------\n Add or parse trailers metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n-For example, in the following commit message\n+\n+A _trailer_ in its simplest form is a key-value pair with a colon as a\n+separator. A _trailer block_ consists of one or more trailers. The\n+trailer block needs to be preceded by a blank line, where a _blank line_\n+is either an empty or a whitespace-only line. For example, in the\n+following commit message\n \n ------------------------------------------------\n subject\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541471","messageId":"V2_trailer_key_format.619@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 6/9] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:05Z","receivedAt":"2026-04-13T10:23:22Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nA trailer key must consist of ASCII alphanumeric characters and\nhyphens *only*. Let’s document it explicitly instead of relying on\nreaders being conservative and only basing their trailer keys on the\ndocumentation examples.[1]\n\nThe previous commit provided us with an appropriate paragraph to\ndescribe the key format.\n\n† 1: Technically they would then miss out on using digits in them since\n all of the example keys just use letters and hyphens\n\nReported-by: Brendan Jackman \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Remove the “paint by numbers” reference after review (unclear)\n • Add apropos footnote\n • Tweak the paragraph about how we now have a context to describe\n this format\n v1: [had a note about code spelunking (isalnum(3))]\n\n Documentation/git-interpret-trailers.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex bcd79b19bd7..c35fa9c688d 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -18,7 +18,8 @@ Add or parse trailers metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n \n A _trailer_ in its simplest form is a key-value pair with a colon as a\n-separator. A _trailer block_ consists of one or more trailers. The\n+separator. The _key_ consists of ASCII alphanumeric characters and\n+hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n trailer block needs to be preceded by a blank line, where a _blank line_\n is either an empty or a whitespace-only line. For example, in the\n following commit message\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541472","messageId":"V2_trailer_key_format_example.61a@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 7/9] doc: interpret-trailers: add key format example","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:06Z","receivedAt":"2026-04-13T10:23:41Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nAll of the examples speak of the Happy Path where everything works\nas intended. But failure examples can also be instructive. Especially\nfor explaining again, by example, the key format (see previous commit).\n\nThis also allows us to demonstrate trailer block detection with a\nconcrete example.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++\n 1 file changed, 23 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex c35fa9c688d..f215cba4bf0 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -405,6 +405,29 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n+* Here we try to to use three different trailer keys. But it fails\n+ because two of them are not recognized as trailer keys.\n++\n+----\n+$ cat msg.txt\n+subject\n+\n+Skapad-på: some-branch\n+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n+Reviewed-by: Alice \n+$ git interpret-trailers --only-trailers \n\nWe chose to introduce the term “trailer block” into the documentation a\nfew commits ago.[1] It is used in the code though, so it is not a newly\ninvented term.\n\nThat term was useful to explain where the trailers are found (they\n*trail* the message). But it is also useful here, where we explain how\ntrailers are added to existing messages, how trailer blocks are\nfound (beyond the simple case in the introduction), and how the end of\nthe message is found.\n\n† 1: in commit “explain the format after the intro”\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------\n 1 file changed, 14 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex f215cba4bf0..b693e89fd96 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -87,19 +87,21 @@ trailer.sign.key \"Signed-off-by: \"\n in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n \n-By default the new trailer will appear at the end of all the existing\n-trailers. If there is no existing trailer, the new trailer will appear\n-at the end of the input. A blank line will be added before the new\n-trailer if there isn't one already.\n-\n-Existing trailers are extracted from the input by looking for\n-a group of one or more lines that (i) is all trailers, or (ii) contains at\n-least one Git-generated or user-configured trailer and consists of at\n+By default the new trailer will appear at the end of the trailer block.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line (specifically an empty line)\n+will be inserted before the new trailer block in that case.\n+\n+Existing trailers are extracted from the input by looking for the\n+trailer block. Concretely, that is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n least 25% trailers.\n-The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the input or be the last\n-non-whitespace lines before a line that starts with `---` (followed by a\n-space or the end of the line).\n+The trailer block is by definition at the end the the message. The end\n+of the message in turn is either (i) at the end of the input, or (ii)\n+the last non-whitespace lines before a line that starts with `---`\n+(followed by a space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541474","messageId":"V2_trailer_comment_lines.61c@msgid.xyz","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"[PATCH v2 9/9] doc: intepret-trailers: document comment line treatment","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T10:21:08Z","receivedAt":"2026-04-13T10:24:19Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nComment lines have always been ignored but this is not documented.\n\nThis is mostly for completeness since this is unlikely to catch anyone\nby surprise. But we really ought to be reasonably complete here since\nit’s the only documentation page that documents trailers.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex b693e89fd96..b42f957d666 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -103,6 +103,10 @@ of the message in turn is either (i) at the end of the input, or (ii)\n the last non-whitespace lines before a line that starts with `---`\n (followed by a space or the end of the line).\n \n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n+\n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n between the __ and the separator. There can be whitespaces before,\n-- \n2.53.0.32.gf6228eaf9cc\n\n"},{"id":"541476","messageId":"5302cfb4-f2a4-48bf-98ce-98b74e7a6568@app.fastmail.com","threadId":"63233","inReplyTo":"V2_trailer_comment_lines.61c@msgid.xyz","subject":"Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-13T13:26:36Z","receivedAt":"2026-04-13T13:26:59Z","isPatch":true,"body":"> [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment\n\ns/intepret-trailers/interpret-trailers/\n\nDidn’t line up\n\nOn Mon, Apr 13, 2026, at 12:21, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk \n>[snip]\n"},{"id":"541480","messageId":"xmqq5x5ulv41.fsf@gitster.g","threadId":"63233","inReplyTo":"5302cfb4-f2a4-48bf-98ce-98b74e7a6568@app.fastmail.com","subject":"Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-04-13T15:48:14Z","receivedAt":"2026-04-13T15:48:17Z","isPatch":true,"body":"\"Kristoffer Haugsbakk\" writes:\n\n>> [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment\n>\n> s/intepret-trailers/interpret-trailers/\n>\n> Didn’t line up\n\nYup, looking at [0/9], I agree.\n"},{"id":"542925","messageId":"55d5d53a-ec30-4b72-9ff4-c5a0631620ec@app.fastmail.com","threadId":"63233","inReplyTo":"V2_CV_doc_int-tr_key_format.613@msgid.xyz","subject":"Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-08T15:01:30Z","receivedAt":"2026-05-08T15:01:51Z","isPatch":true,"body":"On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk \n>[snip]\n\nSorry to Ben here who I forgot to set on copy. :/\n\n+Cc now.\n"},{"id":"542926","messageId":"36b0e906-4bc2-49bf-9485-2449d347facf@app.fastmail.com","threadId":"63233","inReplyTo":"xmqq5x5ulv41.fsf@gitster.g","subject":"Re: [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-08T15:03:52Z","receivedAt":"2026-05-08T15:04:14Z","isPatch":true,"body":"On Mon, Apr 13, 2026, at 17:48, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>\n>>> [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment\n>>\n>> s/intepret-trailers/interpret-trailers/\n>>\n>> Didn’t line up\n>\n> Yup, looking at [0/9], I agree.\n\nJunio fixed this up when applying. That’s why I didn’t send\na new version.\n\nA by-the-way for others here.\n"},{"id":"543001","messageId":"xmqq1pfivfa3.fsf@gitster.g","threadId":"63233","inReplyTo":"55d5d53a-ec30-4b72-9ff4-c5a0631620ec@app.fastmail.com","subject":"Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-11T02:41:40Z","receivedAt":"2026-05-11T02:41:43Z","isPatch":true,"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail.com wrote:\n>> From: Kristoffer Haugsbakk \n>>[snip]\n>\n> Sorry to Ben here who I forgot to set on copy. :/\n>\n> +Cc now.\n\nIt has been quite a while and I have no recollection if there were\nstill necessary adjustments or not. Is everybody happy with the\nfinal text?\n\nhttps://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/\n\n\n Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++--------\n 1 file changed, 50 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 77b4f63b05..b42f957d66 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -3,7 +3,7 @@ git-interpret-trailers(1)\n \n NAME\n ----\n-git-interpret-trailers - Add or parse structured information in commit messages\n+git-interpret-trailers - Add or parse metadata in commit messages\n \n SYNOPSIS\n --------\n@@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n-headers, at the end of the otherwise free-form part of a commit\n-message. For example, in the following commit message\n+Add or parse trailers metadata at the end of the otherwise\n+free-form part of a commit message, or any other kind of text.\n+\n+A _trailer_ in its simplest form is a key-value pair with a colon as a\n+separator. The _key_ consists of ASCII alphanumeric characters and\n+hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n+trailer block needs to be preceded by a blank line, where a _blank line_\n+is either an empty or a whitespace-only line. For example, in the\n+following commit message\n \n ------------------------------------------------\n subject\n@@ -81,19 +87,25 @@ trailer.sign.key \"Signed-off-by: \"\n in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n \n-By default the new trailer will appear at the end of all the existing\n-trailers. If there is no existing trailer, the new trailer will appear\n-at the end of the input. A blank line will be added before the new\n-trailer if there isn't one already.\n+By default the new trailer will appear at the end of the trailer block.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line (specifically an empty line)\n+will be inserted before the new trailer block in that case.\n \n-Existing trailers are extracted from the input by looking for\n-a group of one or more lines that (i) is all trailers, or (ii) contains at\n-least one Git-generated or user-configured trailer and consists of at\n+Existing trailers are extracted from the input by looking for the\n+trailer block. Concretely, that is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n least 25% trailers.\n-The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the input or be the last\n-non-whitespace lines before a line that starts with `---` (followed by a\n-space or the end of the line).\n+The trailer block is by definition at the end the the message. The end\n+of the message in turn is either (i) at the end of the input, or (ii)\n+the last non-whitespace lines before a line that starts with `---`\n+(followed by a space or the end of the line).\n+\n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n \n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n@@ -107,9 +119,6 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n-Note that trailers do not follow (nor are they intended to follow) many of the\n-rules for RFC 822 headers. For example they do not follow the encoding rule.\n-\n OPTIONS\n -------\n `--in-place`::\n@@ -402,6 +411,29 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n+* Here we try to to use three different trailer keys. But it fails\n+ because two of them are not recognized as trailer keys.\n++\n+----\n+$ cat msg.txt\n+subject\n+\n+Skapad-på: some-branch\n+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n+Reviewed-by: Alice \n+$ git interpret-trailers --only-trailers wrote:\n>\n> \"Kristoffer Haugsbakk\" writes:\n>\n> > On Mon, Apr 13, 2026, at 12:20, kristofferhaugsbakk@fastmail.com wrote:\n> >> From: Kristoffer Haugsbakk \n> >>[snip]\n> >\n> > Sorry to Ben here who I forgot to set on copy. :/\n> >\n> > +Cc now.\n>\n> It has been quite a while and I have no recollection if there were\n> still necessary adjustments or not. Is everybody happy with the\n> final text?\n>\n> https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/\n>\n>\n> Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++++++++--------\n> 1 file changed, 50 insertions(+), 18 deletions(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n> index 77b4f63b05..b42f957d66 100644\n> --- a/Documentation/git-interpret-trailers.adoc\n> +++ b/Documentation/git-interpret-trailers.adoc\n> @@ -3,7 +3,7 @@ git-interpret-trailers(1)\n>\n> NAME\n> ----\n> -git-interpret-trailers - Add or parse structured information in commit messages\n> +git-interpret-trailers - Add or parse metadata in commit messages\n>\n> SYNOPSIS\n> --------\n> @@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]\n>\n> DESCRIPTION\n> -----------\n> -Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n> -headers, at the end of the otherwise free-form part of a commit\n> -message. For example, in the following commit message\n> +Add or parse trailers metadata at the end of the otherwise\n> +free-form part of a commit message, or any other kind of text.\n> +\n> +A _trailer_ in its simplest form is a key-value pair with a colon as a\n> +separator. The _key_ consists of ASCII alphanumeric characters and\n> +hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n> +trailer block needs to be preceded by a blank line, where a _blank line_\n> +is either an empty or a whitespace-only line. For example, in the\n> +following commit message\n>\n> ------------------------------------------------\n> subject\n> @@ -81,19 +87,25 @@ trailer.sign.key \"Signed-off-by: \"\n> in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n> on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n>\n> -By default the new trailer will appear at the end of all the existing\n> -trailers. If there is no existing trailer, the new trailer will appear\n> -at the end of the input. A blank line will be added before the new\n> -trailer if there isn't one already.\n> +By default the new trailer will appear at the end of the trailer block.\n> +A trailer block will be created with only that trailer if a trailer\n> +block does not already exist. Recall that a trailer block needs to be\n> +preceded by a blank line, so a blank line (specifically an empty line)\n> +will be inserted before the new trailer block in that case.\n\n[not strictly related to this patch, but while we're here…]\n\nEven in context, I find the original (and new) paragraph somewhat\njarring. In \"the new trailer,\" there's no antecedent for \"the\ntrailer\", so which new trailer are we talking about? The previous\nparagraph is about \"es\" for --trailer=\": value\".\n\nWe _could_ move this paragraph up one, so that it follows the\nparagraph on trailers being appended when given with --trailer.\n\nEither way, adjusting \"the new trailer\" to \"a new trailer\" might feel\nbetter to me. Other suggestions welcome.\n\n> -Existing trailers are extracted from the input by looking for\n> -a group of one or more lines that (i) is all trailers, or (ii) contains at\n> -least one Git-generated or user-configured trailer and consists of at\n> +Existing trailers are extracted from the input by looking for the\n> +trailer block. Concretely, that is a group of one or more lines that (i)\n> +is all trailers, or (ii) contains at least one Git-generated or\n> +user-configured trailer and consists of at\n> least 25% trailers.\n> -The group must be preceded by one or more empty (or whitespace-only) lines.\n> -The group must either be at the end of the input or be the last\n> -non-whitespace lines before a line that starts with `---` (followed by a\n> -space or the end of the line).\n> +The trailer block is by definition at the end the the message. The end\n> +of the message in turn is either (i) at the end of the input, or (ii)\n> +the last non-whitespace lines before a line that starts with `---`\n> +(followed by a space or the end of the line).\n> +\n> +This command ignores comment lines (see `core.commentString` in\n> +linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n> +and `commit-msg` hooks.\n>\n> When reading trailers, there can be no whitespace before or inside the\n> __, but any number of regular space and tab characters are allowed\n> @@ -107,9 +119,6 @@ key: This is a very long value, with spaces and\n> newlines in it.\n> ------------------------------------------------\n>\n> -Note that trailers do not follow (nor are they intended to follow) many of the\n> -rules for RFC 822 headers. For example they do not follow the encoding rule.\n> -\n> OPTIONS\n> -------\n> `--in-place`::\n> @@ -402,6 +411,29 @@ mv \"\\$1.new\" \"\\$1\"\n> $ chmod +x .git/hooks/commit-msg\n> ------------\n>\n> +* Here we try to to use three different trailer keys. But it fails\n> + because two of them are not recognized as trailer keys.\n> ++\n> +----\n> +$ cat msg.txt\n> +subject\n> +\n> +Skapad-på: some-branch\n> +Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n> +Reviewed-by: Alice \n> +$ git interpret-trailers --only-trailers +$\n> +----\n> ++\n> +Recall that a trailer key has to consist of only ASCII alphanumeric\n> +characters and hyphens, and this does not hold for the two first\n> +supposed trailer keys. And now none are recognized as trailers because\n> +the candidate trailer block has at least one non-trailer line, even\n> +though `Reviewed-by` is a valid trailer key. Recall that a trailer block\n> +has to either (i) be all trailers, or (ii) consist of at least one\n> +Git-generated or user-configured trailer (and some other conditions).\n> +And (ii) is not satisfied since we have not configured any trailer keys.\n> +\n> SEE ALSO\n> --------\n> linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]\n\n\n\n-- \nD. Ben Knoble\n"},{"id":"543998","messageId":"fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com","threadId":"63233","inReplyTo":"CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com","subject":"Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-24T12:41:01Z","receivedAt":"2026-05-24T12:41:23Z","isPatch":true,"body":"On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:\n> Overall looks good to me. Repeating a few points throughout the doc\n> might create headaches if format restrictions are changed, but I think\n> they are essential points worth repeating for now.\n\nThanks for taking a look again. :)\n\n>>[snip]\n>> @@ -81,19 +87,25 @@ trailer.sign.key \"Signed-off-by: \"\n>> in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n>> on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n>>\n>> -By default the new trailer will appear at the end of all the existing\n>> -trailers. If there is no existing trailer, the new trailer will appear\n>> -at the end of the input. A blank line will be added before the new\n>> -trailer if there isn't one already.\n>> +By default the new trailer will appear at the end of the trailer block.\n>> +A trailer block will be created with only that trailer if a trailer\n>> +block does not already exist. Recall that a trailer block needs to be\n>> +preceded by a blank line, so a blank line (specifically an empty line)\n>> +will be inserted before the new trailer block in that case.\n>\n> [not strictly related to this patch, but while we're here…]\n>\n> Even in context, I find the original (and new) paragraph somewhat\n> jarring. In \"the new trailer,\" there's no antecedent for \"the\n> trailer\", so which new trailer are we talking about? The previous\n> paragraph is about \"es\" for --trailer=\": value\".\n>\n> We _could_ move this paragraph up one, so that it follows the\n> paragraph on trailers being appended when given with --trailer.\n>\n> Either way, adjusting \"the new trailer\" to \"a new trailer\" might feel\n> better to me. Other suggestions welcome.\n\nThe paragraph about new trailers originally came right after the\nseparated-by sentence:[1]\n\n By default, a '=' or ':' [...]\n\n ------------------------------------------------\n token: value\n ------------------------------------------------\n\n This means that the trimmed and will be separated by\n `': '` (one colon followed by one space).\n\n By default the new trailer will appear [...]\n\n† 1: dfd66ddf (Documentation: add documentation for 'git\n interpret-trailers', 2014-10-13)\n\nNine years later in [2], a “For convenience, ” was added to that *existing paragraph:\n\n [...]\n `': '` (one colon followed by one space). For convenience, the can be a\n shortened string key (e.g., \"sign\") instead of the full string which should\n appear before the separator on the output (e.g., \"Signed-off-by\"). This can be\n configured using the 'trailer..key' configuration variable.\n\n By default the new trailer will appear at the end [...]\n\n† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)\n\nA little later in [3], that part was split into its own paragraph—and\nexpanded into two more blocks (source block and paragraph):\n\n [...] and will be separated by `': '` (one colon followed\n by one space).\n\n For convenience, a can be configured to [...]\n\n ------------------------------------------------\n key: value\n ------------------------------------------------\n\n in your configuration, [...]\n\n By default the new trailer will appear at the end [...]\n\n† 3: 6ccbc667 (trailer doc: is a or , not both,\n 2023-09-07)\n\n> We _could_ move this paragraph up one, so that it follows the\n> paragraph on trailers being appended when given with --trailer.\n\nBut going back to commit [1], there are two paragraphs that talk about\nhow “By default” the new trailer will be appended to the end:\n\n By default, a '=' or ':' argument given\n using `--trailer` will be appended after the existing trailers only if\n the last trailer has a different (, ) pair (or if there\n is no existing trailer). The and parts will be trimmed\n to remove starting and trailing whitespace, and the resulting trimmed\n and will appear in the message like this:\n\n ------------------------------------------------\n token: value\n ------------------------------------------------\n\n This means that the trimmed and will be separated by\n `': '` (one colon followed by one space).\n\n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n after the commit message part of the ouput, and, if there is no line\n with only spaces at the end of the commit message part, one blank line\n will be added before the new trailer.\n\nThese two seem to overlap? They both talk about appending. Why does one\ntalk about how specifically / and will be treated\nwhen appended, then a later paragraph *also* says that it will be\nappended?\n\nHere is a draft of this part of the doc. I have tried to consolidate\nthese two “By default” paragrahs and be more explicit about what “the\ntrailer” is. I have included one unchanged paragraph before and after\nfor context.\n\n***\n\nSome configuration variables control the way the `--trailer` arguments\nare applied to each input and the way any existing trailer in\nthe input is changed. They also make it possible to\nautomatically add some trailers.\n\nLet's consider new trailers added with `--trailer`.\nBy default, the new trailer will appear at the end of the trailer block.\nAlso by default, this new trailer will only be added\nif the last trailer is different to it.\nA trailer block will be created with only that trailer if a trailer\nblock does not already exist. Recall that a trailer block needs to be\npreceded by a blank line, so a blank line (specifically an empty line)\nwill be inserted before the new trailer block in that case.\n\nMore concretely, this is how the new trailer is added: a `=`\nor `:` argument given using `--trailer` will be appended\nafter the existing trailers. The __ and __ parts will be\ntrimmed to remove starting and trailing whitespace, and the resulting\ntrimmed __ and __ will appear in the output like this:\n\n------------------------------------------------\nkey: value\n------------------------------------------------\n\nThis means that the trimmed __ and __ will be separated by\n\"`:`{nbsp}\" (one colon followed by one space).\n\n***\n\n>[snip]\n>> -a group of one or more lines that (i) is all trailers, or (ii) contains at\n>> -least one Git-generated or user-configured trailer and consists of at\n>> +Existing trailers are extracted from the input by looking for the\n>> +trailer block. Concretely, that is a group of one or more lines that (i)\n>> +is all trailers, or (ii) contains at least one Git-generated or\n>> +user-configured trailer and consists of at\n>>[snip]\n"},{"id":"544129","messageId":"4DD440D4-145A-4A9E-ACBA-8E6ACFA231D1@gmail.com","threadId":"63233","inReplyTo":"fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com","subject":"Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-05-26T21:34:56Z","receivedAt":"2026-05-26T21:35:08Z","isPatch":true,"body":"\n> Le 24 mai 2026 à 08:41, Kristoffer Haugsbakk a écrit :\n> \n> On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:\n>> Overall looks good to me. Repeating a few points throughout the doc\n>> might create headaches if format restrictions are changed, but I think\n>> they are essential points worth repeating for now.\n> \n> Thanks for taking a look again. :)\n\nThank you for working on it :)\n\n>>> [snip]\n>>> @@ -81,19 +87,25 @@ trailer.sign.key \"Signed-off-by: \"\n>>> in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n>>> on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n>>> \n>>> -By default the new trailer will appear at the end of all the existing\n>>> -trailers. If there is no existing trailer, the new trailer will appear\n>>> -at the end of the input. A blank line will be added before the new\n>>> -trailer if there isn't one already.\n>>> +By default the new trailer will appear at the end of the trailer block.\n>>> +A trailer block will be created with only that trailer if a trailer\n>>> +block does not already exist. Recall that a trailer block needs to be\n>>> +preceded by a blank line, so a blank line (specifically an empty line)\n>>> +will be inserted before the new trailer block in that case.\n>> \n>> [not strictly related to this patch, but while we're here…]\n>> \n>> Even in context, I find the original (and new) paragraph somewhat\n>> jarring. In \"the new trailer,\" there's no antecedent for \"the\n>> trailer\", so which new trailer are we talking about? The previous\n>> paragraph is about \"es\" for --trailer=\": value\".\n>> \n>> We _could_ move this paragraph up one, so that it follows the\n>> paragraph on trailers being appended when given with --trailer.\n>> \n>> Either way, adjusting \"the new trailer\" to \"a new trailer\" might feel\n>> better to me. Other suggestions welcome.\n> \n> The paragraph about new trailers originally came right after the\n> separated-by sentence:[1]\n> \n> By default, a '=' or ':' [...]\n> \n> ------------------------------------------------\n> token: value\n> ------------------------------------------------\n> \n> This means that the trimmed and will be separated by\n> `': '` (one colon followed by one space).\n> \n> By default the new trailer will appear [...]\n> \n> † 1: dfd66ddf (Documentation: add documentation for 'git\n> interpret-trailers', 2014-10-13)\n> \n> Nine years later in [2], a “For convenience, ” was added to that *existing paragraph:\n> \n> [...]\n> `': '` (one colon followed by one space). For convenience, the can be a\n> shortened string key (e.g., \"sign\") instead of the full string which should\n> appear before the separator on the output (e.g., \"Signed-off-by\"). This can be\n> configured using the 'trailer..key' configuration variable.\n> \n> By default the new trailer will appear at the end [...]\n> \n> † 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)\n> \n> A little later in [3], that part was split into its own paragraph—and\n> expanded into two more blocks (source block and paragraph):\n> \n> [...] and will be separated by `': '` (one colon followed\n> by one space).\n> \n> For convenience, a can be configured to [...]\n> \n> ------------------------------------------------\n> key: value\n> ------------------------------------------------\n> \n> in your configuration, [...]\n> \n> By default the new trailer will appear at the end [...]\n> \n> † 3: 6ccbc667 (trailer doc: is a or , not both,\n> 2023-09-07)\n> \n>> We _could_ move this paragraph up one, so that it follows the\n>> paragraph on trailers being appended when given with --trailer.\n> \n> But going back to commit [1], there are two paragraphs that talk about\n> how “By default” the new trailer will be appended to the end:\n> \n> By default, a '=' or ':' argument given\n> using `--trailer` will be appended after the existing trailers only if\n> the last trailer has a different (, ) pair (or if there\n> is no existing trailer). The and parts will be trimmed\n> to remove starting and trailing whitespace, and the resulting trimmed\n> and will appear in the message like this:\n> \n> ------------------------------------------------\n> token: value\n> ------------------------------------------------\n> \n> This means that the trimmed and will be separated by\n> `': '` (one colon followed by one space).\n> \n> By default the new trailer will appear at the end of all the existing\n> trailers. If there is no existing trailer, the new trailer will appear\n> after the commit message part of the ouput, and, if there is no line\n> with only spaces at the end of the commit message part, one blank line\n> will be added before the new trailer.\n> \n> These two seem to overlap? They both talk about appending. Why does one\n> talk about how specifically / and will be treated\n> when appended, then a later paragraph *also* says that it will be\n> appended?\n> \n> Here is a draft of this part of the doc. I have tried to consolidate\n> these two “By default” paragrahs and be more explicit about what “the\n> trailer” is. I have included one unchanged paragraph before and after\n> for context.\n\nI’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.\n\nWhether you roll that into this patch series or wait until the dust settles is up to you.\n\n> ***\n> \n> Some configuration variables control the way the `--trailer` arguments\n> are applied to each input and the way any existing trailer in\n> the input is changed. They also make it possible to\n> automatically add some trailers.\n> \n> Let's consider new trailers added with `--trailer`.\n> By default, the new trailer will appear at the end of the trailer block.\n> Also by default, this new trailer will only be added\n> if the last trailer is different to it.\n> A trailer block will be created with only that trailer if a trailer\n> block does not already exist. Recall that a trailer block needs to be\n> preceded by a blank line, so a blank line (specifically an empty line)\n> will be inserted before the new trailer block in that case.\n> \n> More concretely, this is how the new trailer is added: a `=`\n> or `:` argument given using `--trailer` will be appended\n> after the existing trailers. The __ and __ parts will be\n> trimmed to remove starting and trailing whitespace, and the resulting\n> trimmed __ and __ will appear in the output like this:\n> \n> ------------------------------------------------\n> key: value\n> ------------------------------------------------\n> \n> This means that the trimmed __ and __ will be separated by\n> \"`:`{nbsp}\" (one colon followed by one space).\n> \n> ***\n> \n>> [snip]\n>>> -a group of one or more lines that (i) is all trailers, or (ii) contains at\n>>> -least one Git-generated or user-configured trailer and consists of at\n>>> +Existing trailers are extracted from the input by looking for the\n>>> +trailer block. Concretely, that is a group of one or more lines that (i)\n>>> +is all trailers, or (ii) contains at least one Git-generated or\n>>> +user-configured trailer and consists of at\n>>> [snip]\n"},{"id":"544130","messageId":"0faba437-31cf-4004-adaf-2dfcd2274a5b@app.fastmail.com","threadId":"63233","inReplyTo":"4DD440D4-145A-4A9E-ACBA-8E6ACFA231D1@gmail.com","subject":"Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-26T21:42:07Z","receivedAt":"2026-05-26T21:42:28Z","isPatch":true,"body":"On Tue, May 26, 2026, at 23:34, Ben Knoble wrote:\n>> Le 24 mai 2026 à 08:41, Kristoffer Haugsbakk a écrit :\n>>\n>> On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:\n>>> Overall looks good to me. Repeating a few points throughout the doc\n>>> might create headaches if format restrictions are changed, but I think\n>>> they are essential points worth repeating for now.\n>>\n>> Thanks for taking a look again. :)\n>\n> Thank you for working on it :)\n>\n>>[snip]\n>>\n>> Here is a draft of this part of the doc. I have tried to consolidate\n>> these two “By default” paragrahs and be more explicit about what “the\n>> trailer” is. I have included one unchanged paragraph before and after\n>> for context.\n>\n> I’ve read through the below a few times, and I don’t really have much\n> to add for now :) I think that’s a fine improvement.\n>\n> Whether you roll that into this patch series or wait until the dust\n> settles is up to you.\n\nMany thanks!\n"},{"id":"544131","messageId":"5508ee49-2f78-4c3a-accf-a2350666bfb8@app.fastmail.com","threadId":"63233","inReplyTo":"0faba437-31cf-4004-adaf-2dfcd2274a5b@app.fastmail.com","subject":"Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-26T21:45:26Z","receivedAt":"2026-05-26T21:45:47Z","isPatch":true,"body":"On Tue, May 26, 2026, at 23:42, Kristoffer Haugsbakk wrote:\n>>[snip]\n>>\n>> I’ve read through the below a few times, and I don’t really have much\n>> to add for now :) I think that’s a fine improvement.\n>>\n>> Whether you roll that into this patch series or wait until the dust\n>> settles is up to you.\n>\n> Many thanks!\n\nSorry. I forgot to add: the plan right now is to weave it into this series.\n"},{"id":"545190","messageId":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","threadId":"63233","inReplyTo":"CV_doc_int-tr_key_format.533@msgid.xyz","subject":"[PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:18Z","receivedAt":"2026-06-10T21:21:32Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-trailers\n\nTopic summary: Explain the format of trailer keys (alphanum and\nhyphens). This is important to keep in mind so that metadata is not\nlost to simple syntax errors. Also replace some terms and define the\nimportant ones upfront.\n\nTo that end, an overview of the changes:\n\n• Patches 1–3: remove RFC 822 mentions, “metadata” term\n• Patch 4: This command is not just for commit messages\n• Patches 5–7: Explain the format in the simplest case, explain\n the “key” format, and add a new example\n• Patch 8 [new]: join some existing paragraphs that are about the same theme\n since that makes the text flow better\n• Patch 9: Also use the “trailer block” term introduced to the doc in\n patch 5 later in the doc\n• Patch 10 [new]: Rewrite new-trailer paragraphs (relates to patch 8)\n• Patch 11: document line comment behavior\n\n§ Changes in v3\n\nI followed up on D. Ben’s suggestion about thematic paragraphs (patch 8).\n\nI also made a new change as a knock-on to patch 8. That’s patch 10.\n\nI also changed patch 11 (formerly 10): moved it out into its own section.\n\nSee the patches for details. Look for “v3” in the patch Notes.\n\n§ Apologies for very cross-referenced commit messages\n\nLike I wrote on v2.\n\n Here one thing lead to another,\n\nAnd in the process I had to make changes that necessitated *other changes*\nas a knock-on effect. Shuffle some text, need to reshuffle three paragraphs\nlater for consistency. And rather than piling on “While at it”/“Also”, I\nchose to try to make focused commits. (Which is how an idea to explain that\ntrailer keys are alphanum/hyhens-only became eleven patches.)\n\nBut in order to follow up on related items I needed to refer to both future\nand previous commits. And in the process I abandoned the usual “in an\nupcoming commit”/“in a previous commit” in favor of perhaps a gratingly\nprecise “commit ”, e.g.:\n\n The format in its simplest form is easy to describe directly without\n comparing it to anything else; we will do that in the upcoming\n commit “explain the format after the intro”.\n\nand,\n\n This also makes the introduction more consistent with how I chose\n to define trailers in the glossary:[1] “Key-value metadata”. (We will\n introduce “key–value” in the upcoming commit “explain the format after\n the intro”.)\n\n§ Cc\n\n(see v2)\n\n§ In-reply-to: v1\n\n§ Link to v2\n\nhttps://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/\n\n[01/11] doc: interpret-trailers: stop fixating on RFC 822\n[02/11] doc: interpret-trailers: replace “lines” with “metadata”\n[03/11] doc: interpret-trailers: use “metadata” in Name as well\n[04/11] doc: interpret-trailers: not just for commit messages\n[05/11] doc: interpret-trailers: explain the format after the intro\n[06/11] doc: interpret-trailers: explain key format\n[07/11] doc: interpret-trailers: add key format example\n[08/11] doc: interpret-trailers: join new-trailers again\n[09/11] doc: interpret-trailers: commit to “trailer block” term\n[10/11] doc: interpret-trailers: rewrite new-trailers paragraphs\n[11/11] doc: interpret-trailers: document comment line treatment\n\n Documentation/git-interpret-trailers.adoc | 92 ++++++++++++++++-------\n 1 file changed, 66 insertions(+), 26 deletions(-)\n\nInterdiff against v2:\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex b42f957d666..d5e856f5d68 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in\n the input is changed. They also make it possible to\n automatically add some trailers.\n \n-By default, a `=` or `:` argument given\n-using `--trailer` will be appended after the existing trailers only if\n-the last trailer has a different (__, __) pair (or if there\n-is no existing trailer). The __ and __ parts will be trimmed\n-to remove starting and trailing whitespace, and the resulting trimmed\n-__ and __ will appear in the output like this:\n+Let's consider new trailers added with `--trailer`.\n+By default, the new trailer will appear at the end of the trailer block.\n+Also by default, this new trailer will only be added\n+if the last trailer is different to it.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line (specifically an empty line)\n+will be inserted before the new trailer block in that case.\n+\n+More concretely, this is how the new trailer is added: a `=`\n+or `:` argument given using `--trailer` will be appended\n+after the existing trailers. The __ and __ parts will be\n+trimmed to remove starting and trailing whitespace, and the resulting\n+trimmed __ and __ will appear in the output like this:\n \n ------------------------------------------------\n key: value\n@@ -74,6 +82,16 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n+Existing trailers are extracted from the input by looking for the\n+trailer block. Concretely, that is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n+least 25% trailers.\n+The trailer block is by definition at the end the the message. The end\n+of the message in turn is either (i) at the end of the input, or (ii)\n+the last non-whitespace lines before a line that starts with `---`\n+(followed by a space or the end of the line).\n+\n For convenience, a __ can be configured to make using `--trailer`\n shorter to type on the command line. This can be configured using the\n `trailer..key` configuration variable. The __ must be a prefix\n@@ -87,26 +105,6 @@ trailer.sign.key \"Signed-off-by: \"\n in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n \n-By default the new trailer will appear at the end of the trailer block.\n-A trailer block will be created with only that trailer if a trailer\n-block does not already exist. Recall that a trailer block needs to be\n-preceded by a blank line, so a blank line (specifically an empty line)\n-will be inserted before the new trailer block in that case.\n-\n-Existing trailers are extracted from the input by looking for the\n-trailer block. Concretely, that is a group of one or more lines that (i)\n-is all trailers, or (ii) contains at least one Git-generated or\n-user-configured trailer and consists of at\n-least 25% trailers.\n-The trailer block is by definition at the end the the message. The end\n-of the message in turn is either (i) at the end of the input, or (ii)\n-the last non-whitespace lines before a line that starts with `---`\n-(followed by a space or the end of the line).\n-\n-This command ignores comment lines (see `core.commentString` in\n-linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n-and `commit-msg` hooks.\n-\n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n between the __ and the separator. There can be whitespaces before,\n@@ -119,6 +117,16 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n+OTHER RULES\n+-----------\n+\n+What was covered in the previous section are the rules that are relevant\n+for regular use. The following points are included for completeness.\n+\n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n+\n OPTIONS\n -------\n `--in-place`::\nRange-diff against v2:\n 1: e5d58237bc2 = 1: e5d58237bc2 doc: interpret-trailers: stop fixating on RFC 822\n 2: 5ddd39bf157 = 2: 5ddd39bf157 doc: interpret-trailers: replace “lines” with “metadata”\n 3: 9f0227a1978 = 3: 9f0227a1978 doc: interpret-trailers: use “metadata” in Name as well\n 4: 4cb26810d4e = 4: 4cb26810d4e doc: interpret-trailers: not just for commit messages\n 5: 196c91bebe3 = 5: 196c91bebe3 doc: interpret-trailers: explain the format after the intro\n 6: 688ea55599a = 6: 688ea55599a doc: interpret-trailers: explain key format\n 7: e6eafbd641f = 7: e6eafbd641f doc: interpret-trailers: add key format example\n -: ----------- > 8: 8849ace33e6 doc: interpret-trailers: join new-trailers again\n 8: f14d641309c ! 9: 8323b84e134 doc: interpret-trailers: commit to “trailer block” term\n @@ Commit message\n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-interpret-trailers.adoc ##\n -@@ Documentation/git-interpret-trailers.adoc: trailer.sign.key \"Signed-off-by: \"\n - in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n - on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n +@@ Documentation/git-interpret-trailers.adoc: key: value\n + This means that the trimmed __ and __ will be separated by\n + \"`:`{nbsp}\" (one colon followed by one space).\n \n -By default the new trailer will appear at the end of all the existing\n -trailers. If there is no existing trailer, the new trailer will appear\n @@ Documentation/git-interpret-trailers.adoc: trailer.sign.key \"Signed-off-by: \"\n +the last non-whitespace lines before a line that starts with `---`\n +(followed by a space or the end of the line).\n \n - When reading trailers, there can be no whitespace before or inside the\n - __, but any number of regular space and tab characters are allowed\n + For convenience, a __ can be configured to make using `--trailer`\n + shorter to type on the command line. This can be configured using the\n -: ----------- > 10: c7495c3b39e doc: interpret-trailers: rewrite new-trailers paragraphs\n 9: 78125ab39f1 ! 11: fc38e8660f0 doc: intepret-trailers: document comment line treatment\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: intepret-trailers: document comment line treatment\n + doc: interpret-trailers: document comment line treatment\n \n Comment lines have always been ignored but this is not documented.\n \n @@ Commit message\n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-interpret-trailers.adoc ##\n -@@ Documentation/git-interpret-trailers.adoc: of the message in turn is either (i) at the end of the input, or (ii)\n - the last non-whitespace lines before a line that starts with `---`\n - (followed by a space or the end of the line).\n +@@ Documentation/git-interpret-trailers.adoc: key: This is a very long value, with spaces and\n + newlines in it.\n + ------------------------------------------------\n \n ++OTHER RULES\n ++-----------\n ++\n ++What was covered in the previous section are the rules that are relevant\n ++for regular use. The following points are included for completeness.\n ++\n +This command ignores comment lines (see `core.commentString` in\n +linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n +and `commit-msg` hooks.\n +\n - When reading trailers, there can be no whitespace before or inside the\n - __, but any number of regular space and tab characters are allowed\n - between the __ and the separator. There can be whitespaces before,\n + OPTIONS\n + -------\n + `--in-place`::\n\nbase-commit: 5361983c075154725be47b65cca9a2421789e410\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545191","messageId":"V3_less_RFC_822_focus.8a4@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 01/11] doc: interpret-trailers: stop fixating on RFC 822","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:19Z","receivedAt":"2026-06-10T21:21:52Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command handles the trailers metadata format. But the command\nisn’t introduced as such; it is instead introduced by stating that\nthese trailer lines look similar to RFC 822 email headers.\n\nThis is overwrought; most people do not deal directly with email\nheaders, and certainly not email RFCs.\n\nTrailers are just key–value pairs that, like email headers, use colon\nas the separator. The format in its simplest form is easy to describe\ndirectly without comparing it to anything else; we will do that in the\nupcoming commit “explain the format after the intro”.\n\nFor now, let’s:\n\n• remove the first mention of email headers;\n• keep the second, innocuous comparison with email line folding in the\n middle; and\n• remove the now-unneeded disclaimer that trailers do not share many of\n the features of RFC 822 email headers—there is no invitation to\n speculate that trailers would follow any other email format rules\n since we do not compare them directly any more.\n\n***\n\nTalking about trailers as an RFC 822/2822-like format seems to go back\nto the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated\nthis command and in turn the first trailer support in git(1) beyond\nadding s-o-b lines.\n\n† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Use `***` as a thematic break instead of `❦`\n • Change to “metadata” instead of “key–value pairs” since this series\n version adds a paragraph after this one where we dig into this\n term. And “metadata” describes the purpose of this format.\n\n Documentation/git-interpret-trailers.adoc | 9 +++------\n 1 file changed, 3 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 77b4f63b05c..1878848ad2a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n-headers, at the end of the otherwise free-form part of a commit\n-message. For example, in the following commit message\n+Add or parse _trailer_ lines at the end of the otherwise\n+free-form part of a commit message. For example, in the following commit\n+message\n \n ------------------------------------------------\n subject\n@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n-Note that trailers do not follow (nor are they intended to follow) many of the\n-rules for RFC 822 headers. For example they do not follow the encoding rule.\n-\n OPTIONS\n -------\n `--in-place`::\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545192","messageId":"V3_metadata_not_lines.8a5@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:20Z","receivedAt":"2026-06-10T21:22:11Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe removed the initial comparison to email headers in the previous\ncommit. Now the introduction paragraph just says “trailer lines”, and\nthe only hint that this is metadata/structured information is the\n“otherwise free-form” phrase.\n\nLet’s replace “lines” with “metadata” since that is their purpose.\nThis also makes the introduction more consistent with how I chose\nto define trailers in the glossary:[1] “Key-value metadata”. (We will\nintroduce “key–value” in the upcoming commit “explain the format after\nthe intro”.)\n\n† 1: 68e3c69e (Documentation/glossary: describe \"trailer\", 2024-11-17)\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 1878848ad2a..3f60fd9b720 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines at the end of the otherwise\n+Add or parse trailers metadata at the end of the otherwise\n free-form part of a commit message. For example, in the following commit\n message\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545193","messageId":"V3_metadata_Name_section.8a6@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 03/11] doc: interpret-trailers: use “metadata” in Name as well","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:21Z","receivedAt":"2026-06-10T21:22:30Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe now since the previous commit introduce the format as “trailers\nmetadata”. We can replace “structured information” with “metadata”\nin the “Name” section to be consistent.\n\nWhile “structured information” does emphasize that the data is not\nloosely structured, we also say that this command adds to or parses\nthis format. I don’t think that we need to emphasize that it is\nstructured since clearly there is some structure there.\n\nBoth “metadata” and “structured information” can convey the same\ninformation. But “metadata” is shorter and easier to deploy since\nit’s just one word.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 3f60fd9b720..4e92c8299bb 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -3,7 +3,7 @@ git-interpret-trailers(1)\n \n NAME\n ----\n-git-interpret-trailers - Add or parse structured information in commit messages\n+git-interpret-trailers - Add or parse metadata in commit messages\n \n SYNOPSIS\n --------\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545194","messageId":"V3_cmt_msg_or_other_texts.8a7@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 04/11] doc: interpret-trailers: not just for commit messages","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:22Z","receivedAt":"2026-06-10T21:22:49Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command doesn’t interface with commits directly. You can\ninterpret or modify any kind of text, even though commit messages\nare the most relevant.\n\nThe git(1) suite also isn’t restricted to only direct commit support\nsince git-tag(1) learned `--trailer` in 066cef77 (builtin/tag: add\n--trailer option, 2024-05-05)\n\nNow, we already introduce the command in the “Name” section as dealing\nwith commit messages as well. That is fine since that intro line needs\nto remain pretty short.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 4e92c8299bb..7329e710e1a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty]\n DESCRIPTION\n -----------\n Add or parse trailers metadata at the end of the otherwise\n-free-form part of a commit message. For example, in the following commit\n-message\n+free-form part of a commit message, or any other kind of text.\n+For example, in the following commit message\n \n ------------------------------------------------\n subject\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545195","messageId":"V3_trailer_explain_format.8a8@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 05/11] doc: interpret-trailers: explain the format after the intro","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:23Z","receivedAt":"2026-06-10T21:23:08Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nYou need to read the entire “Description” section in order to understand\nthe full trailer format. But there are many nuances, so that’s fine.\nAs a starter though we have an introductory example.[1] That turns out\nto be crucial; the rest of this section talks about the mechanics of the\ncommand and only incidentally the format itself.\n\nNow, although the example might arguably be self-explanatory, we can\nadd a little preamble which defines the format in its simplest form as\nwell as define the most important terms.\n\nNote that we name the “blank line” rule since I want to use that term\nevery time it comes up. It gets very mildly obfuscated if you call it a\n“blank line” in one place[2] and “empty (or whitespace-only) ...” in\nanother one.[3]\n\nWe will define the format of the *key* in the next commit.\n\n† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,\n 2023-06-15)\n† 2: `Documentation/git-interpret-trailers.adoc:86` in\n 5361983c (The 22nd batch, 2026-03-27)\n† 3: `Documentation/git-interpret-trailers.adoc:93` in\n 5361983c (The 22nd batch, 2026-03-27)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n • PS: Suggested here: https://lore.kernel.org/git/8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com/#t\n • (My tardiness on this topic has made these reminders necessary,\n if only for my own reference)\n\n Documentation/git-interpret-trailers.adoc | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 7329e710e1a..bcd79b19bd7 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -16,7 +16,12 @@ DESCRIPTION\n -----------\n Add or parse trailers metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n-For example, in the following commit message\n+\n+A _trailer_ in its simplest form is a key-value pair with a colon as a\n+separator. A _trailer block_ consists of one or more trailers. The\n+trailer block needs to be preceded by a blank line, where a _blank line_\n+is either an empty or a whitespace-only line. For example, in the\n+following commit message\n \n ------------------------------------------------\n subject\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545196","messageId":"V3_trailer_key_format.8a9@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 06/11] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:24Z","receivedAt":"2026-06-10T21:23:28Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nA trailer key must consist of ASCII alphanumeric characters and\nhyphens *only*. Let’s document it explicitly instead of relying on\nreaders being conservative and only basing their trailer keys on the\ndocumentation examples.[1]\n\nThe previous commit provided us with an appropriate paragraph to\ndescribe the key format.\n\n† 1: Technically they would then miss out on using digits in them since\n all of the example keys just use letters and hyphens\n\nReported-by: Brendan Jackman \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/\n • Remove the “paint by numbers” reference after review (unclear)\n • Add apropos footnote\n • Tweak the paragraph about how we now have a context to describe\n this format\n v1: [had a note about code spelunking (isalnum(3))]\n\n Documentation/git-interpret-trailers.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex bcd79b19bd7..c35fa9c688d 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -18,7 +18,8 @@ Add or parse trailers metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n \n A _trailer_ in its simplest form is a key-value pair with a colon as a\n-separator. A _trailer block_ consists of one or more trailers. The\n+separator. The _key_ consists of ASCII alphanumeric characters and\n+hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n trailer block needs to be preceded by a blank line, where a _blank line_\n is either an empty or a whitespace-only line. For example, in the\n following commit message\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545197","messageId":"V3_trailer_key_format_example.8aa@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 07/11] doc: interpret-trailers: add key format example","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:25Z","receivedAt":"2026-06-10T21:23:47Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nAll of the examples speak of the Happy Path where everything works\nas intended. But failure examples can also be instructive. Especially\nfor explaining again, by example, the key format (see previous commit).\n\nThis also allows us to demonstrate trailer block detection with a\nconcrete example.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++\n 1 file changed, 23 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex c35fa9c688d..f215cba4bf0 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -405,6 +405,29 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n+* Here we try to to use three different trailer keys. But it fails\n+ because two of them are not recognized as trailer keys.\n++\n+----\n+$ cat msg.txt\n+subject\n+\n+Skapad-på: some-branch\n+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n+Reviewed-by: Alice \n+$ git interpret-trailers --only-trailers \n\nThere are three trailers that talk about how a new trailer is added.\nBut the first one is separated from the other two by two paragraphs\nabout how `key-alias` can make using `--trailer` more convenient. This\nshort how-to does not follow thematically from the previous paragraph,\nand can wait until we have fully described how a new trailer is\nadded. So let’s move the three paragraphs about the new-trailer topic\ntogether and move the how-to paragraphs after that.\n\n***\n\nLet’s now review the history of the document. Even if the document\nis not quite correct in its current state, just doing the apparently\nobvious edit without considering the history does not respect the\neffort that went into changing the document in the past.\n\nThese three paragraphs were originally next to each other, in the first\nversion of the doc.[1] But extra sentences about this how-to topic was\nadded to the first paragraph nine years later:[2]\n\n [...]\n `': '` (one colon followed by one space). For convenience, the\n can be a shortened string key (e.g., \"sign\") instead of the\n full string which should [...]\n\nAnd then it was split into it’s own paragraph a little later.[3]\n\nThis evolution shows, in my opinion, that this how-to never followed\nthematically from the existing topic. Which means that there is nothing\nthat was potentially lost to time that we need to restore or respect.\n\n† 1: dfd66ddf (Documentation: add documentation for 'git\n interpret-trailers', 2014-10-13)\n† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)\n† 3: 6ccbc667 (trailer doc: is a or , not both,\n 2023-09-07)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3: [new]\n • Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/\n • Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]\n \n 🔗 1: https://lore.kernel.org/git/xmqqpl1zsv8s.fsf@gitster.g/\n\n Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex f215cba4bf0..759cdb6e18e 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -74,19 +74,6 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-For convenience, a __ can be configured to make using `--trailer`\n-shorter to type on the command line. This can be configured using the\n-`trailer..key` configuration variable. The __ must be a prefix\n-of the full __ string, although case sensitivity does not matter. For\n-example, if you have\n-\n-------------------------------------------------\n-trailer.sign.key \"Signed-off-by: \"\n-------------------------------------------------\n-\n-in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n-on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n-\n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n at the end of the input. A blank line will be added before the new\n@@ -101,6 +88,19 @@ The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with `---` (followed by a\n space or the end of the line).\n \n+For convenience, a __ can be configured to make using `--trailer`\n+shorter to type on the command line. This can be configured using the\n+`trailer..key` configuration variable. The __ must be a prefix\n+of the full __ string, although case sensitivity does not matter. For\n+example, if you have\n+\n+------------------------------------------------\n+trailer.sign.key \"Signed-off-by: \"\n+------------------------------------------------\n+\n+in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n+on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n+\n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n between the __ and the separator. There can be whitespaces before,\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545199","messageId":"V3_trailer_block_term.8ac@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 09/11] doc: interpret-trailers: commit to “trailer block” term","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:27Z","receivedAt":"2026-06-10T21:24:26Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe chose to introduce the term “trailer block” into the documentation a\nfew commits ago.[1] It is used in the code though, so it is not a newly\ninvented term.\n\nThat term was useful to explain where the trailers are found (they\n*trail* the message). But it is also useful here, where we explain how\ntrailers are added to existing messages, how trailer blocks are\nfound (beyond the simple case in the introduction), and how the end of\nthe message is found.\n\n† 1: in commit “explain the format after the intro”\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------\n 1 file changed, 14 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 759cdb6e18e..9f4c84abfd9 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -74,19 +74,21 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-By default the new trailer will appear at the end of all the existing\n-trailers. If there is no existing trailer, the new trailer will appear\n-at the end of the input. A blank line will be added before the new\n-trailer if there isn't one already.\n-\n-Existing trailers are extracted from the input by looking for\n-a group of one or more lines that (i) is all trailers, or (ii) contains at\n-least one Git-generated or user-configured trailer and consists of at\n+By default the new trailer will appear at the end of the trailer block.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line (specifically an empty line)\n+will be inserted before the new trailer block in that case.\n+\n+Existing trailers are extracted from the input by looking for the\n+trailer block. Concretely, that is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n least 25% trailers.\n-The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the input or be the last\n-non-whitespace lines before a line that starts with `---` (followed by a\n-space or the end of the line).\n+The trailer block is by definition at the end the the message. The end\n+of the message in turn is either (i) at the end of the input, or (ii)\n+the last non-whitespace lines before a line that starts with `---`\n+(followed by a space or the end of the line).\n \n For convenience, a __ can be configured to make using `--trailer`\n shorter to type on the command line. This can be configured using the\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545200","messageId":"V3_trailer_comment_lines.8ad@msgid.xyz","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"[PATCH v3 11/11] doc: interpret-trailers: document comment line treatment","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T21:21:29Z","receivedAt":"2026-06-10T21:25:07Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nComment lines have always been ignored but this is not documented.\n\nThis is mostly for completeness since this is unlikely to catch anyone\nby surprise. But we really ought to be reasonably complete here since\nit’s the only documentation page that documents trailers.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3:\n • Msg: finally fix area\n • Demote this point to its own “other rules” section, out of the main\n running text. It is not important enough for the main text.\n • Since writing this I have realized that we can go into that long\n \n # ----- >8 ----\n \n Commit message separator scissor line, maybe other things. But I stop\n short here. These things are even less likely to become a problem for\n anyone. And maybe we’ll add them later?\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex fb9b1e94dd7..d5e856f5d68 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n+OTHER RULES\n+-----------\n+\n+What was covered in the previous section are the rules that are relevant\n+for regular use. The following points are included for completeness.\n+\n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n+\n OPTIONS\n -------\n `--in-place`::\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545205","messageId":"CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com","threadId":"63233","inReplyTo":"V3_join_paragraphs.8ab@msgid.xyz","subject":"Re: [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-06-10T22:00:09Z","receivedAt":"2026-06-10T22:00:24Z","isPatch":true,"body":"On Wed, Jun 10, 2026 at 5:24 PM wrote:\n>\n> From: Kristoffer Haugsbakk \n>\n> There are three trailers that talk about how a new trailer is added.\n\n3 \"paragraphs\"? :)\n\n\n> But the first one is separated from the other two by two paragraphs\n> about how `key-alias` can make using `--trailer` more convenient. This\n> short how-to does not follow thematically from the previous paragraph,\n> and can wait until we have fully described how a new trailer is\n> added. So let’s move the three paragraphs about the new-trailer topic\n> together and move the how-to paragraphs after that.\n\n[snip]\n"},{"id":"545206","messageId":"a6c5a9ec-a118-454f-953c-1323aa716c54@app.fastmail.com","threadId":"63233","inReplyTo":"CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com","subject":"Re: [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:13:24Z","receivedAt":"2026-06-10T22:13:46Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 00:00, D. Ben Knoble wrote:\n> On Wed, Jun 10, 2026 at 5:24 PM wrote:\n>>\n>> From: Kristoffer Haugsbakk \n>>\n>> There are three trailers that talk about how a new trailer is added.\n>\n> 3 \"paragraphs\"? :)\n\nOh doh! Thanks. ;)\n\n>[snip]\n"},{"id":"545211","messageId":"xmqqcxxyt4op.fsf@gitster.g","threadId":"63233","inReplyTo":"V3_CV_doc_int-tr_key_format.8a3@msgid.xyz","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-10T22:24:06Z","receivedAt":"2026-06-10T22:24:09Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> Interdiff against v2:\n> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n> index b42f957d666..d5e856f5d68 100644\n> --- a/Documentation/git-interpret-trailers.adoc\n> +++ b/Documentation/git-interpret-trailers.adoc\n> @@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in\n> the input is changed. They also make it possible to\n> automatically add some trailers.\n> \n> -By default, a `=` or `:` argument given\n> -using `--trailer` will be appended after the existing trailers only if\n> -the last trailer has a different (__, __) pair (or if there\n> -is no existing trailer). The __ and __ parts will be trimmed\n> -to remove starting and trailing whitespace, and the resulting trimmed\n> -__ and __ will appear in the output like this:\n> +Let's consider new trailers added with `--trailer`.\n> +By default, the new trailer will appear at the end of the trailer block.\n> +Also by default, this new trailer will only be added\n> +if the last trailer is different to it.\n\nThe new text is more succinct here.\n\n> +A trailer block will be created with only that trailer if a trailer\n> +block does not already exist. Recall that a trailer block needs to be\n> +preceded by a blank line, so a blank line (specifically an empty line)\n> +will be inserted before the new trailer block in that case.\n\nIf you want to stress that a line with only whitespaces on it does\nnot count as a blank line for the purpose of this paragraph, you can\nconsistently say \"an empty line\" withotu saying \"a blank line\", and\nyou do not need to have \"(specifically an empty lline)\" there.\n\n> +More concretely, this is how the new trailer is added: a `=`\n> +or `:` argument given using `--trailer` will be appended\n> +after the existing trailers. The __ and __ parts will be\n> +trimmed to remove starting and trailing whitespace, and the resulting\n> +trimmed __ and __ will appear in the output like this:\n\n\"More concretely\" here feels a bit out of place, as the three paragraphs\nwe saw so far aren't really progression of the same thing. First we\nsaw when a new trailer line is added, second we learned that an\nextra empty line may be added in addition to the new trailer line.\nWhat we are about to mention is orthogonal: how each trailer line\nwould look like. There is no more or less concrete about it.\n\n> ------------------------------------------------\n> key: value\n> @@ -74,6 +82,16 @@ key: value\n> This means that the trimmed __ and __ will be separated by\n> \"`:`{nbsp}\" (one colon followed by one space).\n> \n> +Existing trailers are extracted from the input by looking for the\n> +trailer block. Concretely, that is a group of one or more lines that (i)\n\n\"Concretely, that is a\" -> \"A trailer block is a\".\n\n> +is all trailers, or (ii) contains at least one Git-generated or\n> +user-configured trailer and consists of at\n> +least 25% trailers.\n\nHmph, isn't (i) a narrow subset of (ii)?\n\n> +The trailer block is by definition at the end the the message. The end\n> +of the message in turn is either (i) at the end of the input, or (ii)\n\n\"at the end the the message\" -> \"at the end of the commit log\nmessage\", and \"the input\" -> \"the message\", probably.\n\nThe latter is because not everybody is \"parsing\" the message to futz\nwith trailers, using the message as \"input\", and some are \"writing\nout\" the message, using it as \"output\".\n\n> +the last non-whitespace lines before a line that starts with `---`\n> +(followed by a space or the end of the line).\n\nOK.\n"},{"id":"545223","messageId":"DJ5W2I8UYXAA.3O4JQUHFMKP5X@lfurio.us","threadId":"63233","inReplyTo":"V3_metadata_not_lines.8a5@msgid.xyz","subject":"Re: [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"Matt Hunter","fromEmail":"m@lfurio.us","sentAt":"2026-06-11T03:10:32Z","receivedAt":"2026-06-11T03:10:39Z","isPatch":true,"body":"On Wed Jun 10, 2026 at 5:21 PM EDT, kristofferhaugsbakk wrote:\n>\n> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n> index 1878848ad2a..3f60fd9b720 100644\n> --- a/Documentation/git-interpret-trailers.adoc\n> +++ b/Documentation/git-interpret-trailers.adoc\n> @@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]\n> \n> DESCRIPTION\n> -----------\n> -Add or parse _trailer_ lines at the end of the otherwise\n> +Add or parse trailers metadata at the end of the otherwise\n\nfwiw, I think \"trailer metadata\" reads more naturally.\n"},{"id":"545263","messageId":"xmqq1pedthkv.fsf@gitster.g","threadId":"63233","inReplyTo":"xmqqcxxyt4op.fsf@gitster.g","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-11T11:57:52Z","receivedAt":"2026-06-11T11:57:55Z","isPatch":true,"body":"Junio C Hamano writes:\n\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> Interdiff against v2:\n>> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n>> ...\n\nBy the way, what I queued last night was missing [10/11] as I used\n\"b4 am\" to grab the latest thread messages by giving the message-id\nof the cover letter, but somehow [10/11] had a bogus value in the\ne-mail header.\n\n Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs\n Date: Wed, 10 Jun 2026 23:21:28 +0200\n Message-ID: <>\n X-Mailer: git-send-email 2.54.0.22.g9e26862b904\n\nSo, I reverted to the old and battle tested way to pick these 11\nmessages manually in my newsreader to replace the topic.\n\nIf you have a chance, could you investigate where the send-out\nprocess went wrong and gave one message a bogus ID? I am worried if\nyou may have triggered a bug in send-email, in which case we would\nwant to fix it to avoid hurting other users.\n\nThanks.\n"},{"id":"545264","messageId":"f738e97b-1aa6-492f-82df-c284a2f94c6a@app.fastmail.com","threadId":"63233","inReplyTo":"xmqq1pedthkv.fsf@gitster.g","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-11T12:05:58Z","receivedAt":"2026-06-11T12:06:20Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 13:57, Junio C Hamano wrote:\n> Junio C Hamano writes:\n>\n>> kristofferhaugsbakk@fastmail.com writes:\n>>\n>>> Interdiff against v2:\n>>> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\n>>> ...\n>\n> By the way, what I queued last night was missing [10/11] as I used\n> \"b4 am\" to grab the latest thread messages by giving the message-id\n> of the cover letter, but somehow [10/11] had a bogus value in the\n> e-mail header.\n>\n> Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite\n> new-trailers paragraphs\n> Date: Wed, 10 Jun 2026 23:21:28 +0200\n> Message-ID: <>\n> X-Mailer: git-send-email 2.54.0.22.g9e26862b904\n>\n> So, I reverted to the old and battle tested way to pick these 11\n> messages manually in my newsreader to replace the topic.\n>\n> If you have a chance, could you investigate where the send-out\n> process went wrong and gave one message a bogus ID? I am worried if\n> you may have triggered a bug in send-email, in which case we would\n> want to fix it to avoid hurting other users.\n\nI’ll investigate. It’s 99.99% chance a problem on my end, created by me.\n\nSorry for the trouble!\n"},{"id":"545266","messageId":"da28347f-7790-4906-964c-5551c86837c4@app.fastmail.com","threadId":"63233","inReplyTo":"f738e97b-1aa6-492f-82df-c284a2f94c6a@app.fastmail.com","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-11T12:53:14Z","receivedAt":"2026-06-11T12:53:36Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 14:05, Kristoffer Haugsbakk wrote:\n>>>>[snip]\n>>>> ...\n>>\n>> By the way, what I queued last night was missing [10/11] as I used\n>> \"b4 am\" to grab the latest thread messages by giving the message-id\n>> of the cover letter, but somehow [10/11] had a bogus value in the\n>> e-mail header.\n>>\n>> Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite\n>> new-trailers paragraphs\n>> Date: Wed, 10 Jun 2026 23:21:28 +0200\n>> Message-ID: <>\n>> X-Mailer: git-send-email 2.54.0.22.g9e26862b904\n>>\n>> So, I reverted to the old and battle tested way to pick these 11\n>> messages manually in my newsreader to replace the topic.\n>>\n>> If you have a chance, could you investigate where the send-out\n>> process went wrong and gave one message a bogus ID? I am worried if\n>> you may have triggered a bug in send-email, in which case we would\n>> want to fix it to avoid hurting other users.\n>\n> I’ll investigate. It’s 99.99% chance a problem on my end, created by me.\n>\n> Sorry for the trouble!\n\nIt was as stupid and embarrassing as it looked at first glance.\nA search-and-replace on the format-patch output which was missing\na target value.\n\nI’m very sorry again.\n"},{"id":"545686","messageId":"26c2fcb2-2618-4bb9-a6e4-a6135934556d@app.fastmail.com","threadId":"63233","inReplyTo":"DJ5W2I8UYXAA.3O4JQUHFMKP5X@lfurio.us","subject":"Re: [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-16T20:32:02Z","receivedAt":"2026-06-16T20:32:24Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 05:10, Matt Hunter wrote:\n> On Wed Jun 10, 2026 at 5:21 PM EDT, kristofferhaugsbakk wrote:\n>>[snip]\n>> DESCRIPTION\n>> -----------\n>> -Add or parse _trailer_ lines at the end of the otherwise\n>> +Add or parse trailers metadata at the end of the otherwise\n>\n> fwiw, I think \"trailer metadata\" reads more naturally.\n\nYou’re right that your version reads more naturally. I went back and\nforth on this.\n\n1. We’re introducing the jargon, and the format is often discussed as\n plural “trailers”, with its constituent parts being singular\n “trailer”\n2. What this replaces uses “trailer”, but it rescues the plural mood\n with “lines”\n3. This is very soon going to go into the constituent parts, including\n each trailer, so we’re contrasting the concept name (trailers) with\n its parts\n\nBut I think your version is overall better. It reads better and there is\nno way to confuse “trailer metadata” (trailers as a collection) with\njust a single “trailer”.\n"},{"id":"545695","messageId":"DJASSI4SSB3E.3JDRTZ3UNTSC4@lfurio.us","threadId":"63233","inReplyTo":"26c2fcb2-2618-4bb9-a6e4-a6135934556d@app.fastmail.com","subject":"Re: [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"Matt Hunter","fromEmail":"m@lfurio.us","sentAt":"2026-06-16T21:39:44Z","receivedAt":"2026-06-16T21:39:51Z","isPatch":true,"body":"On Tue Jun 16, 2026 at 4:32 PM EDT, Kristoffer Haugsbakk wrote:\n> On Thu, Jun 11, 2026, at 05:10, Matt Hunter wrote:\n>> On Wed Jun 10, 2026 at 5:21 PM EDT, kristofferhaugsbakk wrote:\n>>>[snip]\n>>> DESCRIPTION\n>>> -----------\n>>> -Add or parse _trailer_ lines at the end of the otherwise\n>>> +Add or parse trailers metadata at the end of the otherwise\n>>\n>> fwiw, I think \"trailer metadata\" reads more naturally.\n>\n> You’re right that your version reads more naturally. I went back and\n> forth on this.\n\nAfter reading your points, I started debating the grammatical\ncorrectness of it to myself too. Though I think I stand by my original\nknee-jerk response.\n\n>\n> 1. We’re introducing the jargon, and the format is often discussed as\n> plural “trailers”, with its constituent parts being singular\n> “trailer”\n> 2. What this replaces uses “trailer”, but it rescues the plural mood\n> with “lines”\n> 3. This is very soon going to go into the constituent parts, including\n> each trailer, so we’re contrasting the concept name (trailers) with\n> its parts\n>\n> But I think your version is overall better. It reads better and there is\n> no way to confuse “trailer metadata” (trailers as a collection) with\n> just a single “trailer”.\n\nYes, \"metadata\" reads as a hint to me that interpret-trailers works with\nthe overall trailer block too.\n\nAnother thought I had after seeing this again is that the text could\njust say \"Add or parse trailers at the end ...\", but \"metadata\" is a lot\nmore useful, since it's an introduction to what trailers _are_. So the\npatch is an improvement over the original context imo.\n"},{"id":"545794","messageId":"729baf6b-53ea-4e8d-95ab-5935667e66c2@app.fastmail.com","threadId":"63233","inReplyTo":"xmqqcxxyt4op.fsf@gitster.g","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T19:45:31Z","receivedAt":"2026-06-17T19:46:03Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 00:24, Junio C Hamano wrote:\n>[snip]\n>> +A trailer block will be created with only that trailer if a trailer\n>> +block does not already exist. Recall that a trailer block needs to be\n>> +preceded by a blank line, so a blank line (specifically an empty line)\n>> +will be inserted before the new trailer block in that case.\n>\n> If you want to stress that a line with only whitespaces on it does\n> not count as a blank line for the purpose of this paragraph, you can\n> consistently say \"an empty line\" withotu saying \"a blank line\", and\n> you do not need to have \"(specifically an empty lline)\" there.\n\nOkay, I’ll make it shorter.\n\nIt felt too long for a simple concept indeed.\n\n>\n>> +More concretely, this is how the new trailer is added: a `=`\n>> +or `:` argument given using `--trailer` will be appended\n>> +after the existing trailers. The __ and __ parts will be\n>> +trimmed to remove starting and trailing whitespace, and the resulting\n>> +trimmed __ and __ will appear in the output like this:\n>\n> \"More concretely\" here feels a bit out of place, as the three paragraphs\n> we saw so far aren't really progression of the same thing. First we\n> saw when a new trailer line is added, second we learned that an\n> extra empty line may be added in addition to the new trailer line.\n> What we are about to mention is orthogonal: how each trailer line\n> would look like. There is no more or less concrete about it.\n\nYeah, I think I see. I thought this would be continuation into the more\nnuts and bolts of it, where we move from discussing the concepts to the\nconcrete placeholders, so to speak.\n\nI thought I needed a phrase to connect the paragraphs. But now I don’t\nthink I do. Just dropping that phrase:\n\n Let's consider new trailers added with `--trailer`.\n By default, the new trailer will appear at the end of the trailer block.\n Also by default, this new trailer will only be added\n if the last trailer is different to it.\n A trailer block will be created with only that trailer if a trailer\n block does not already exist. Recall that a trailer block needs to be\n preceded by a blank line, so a blank line (specifically an empty line)\n will be inserted before the new trailer block in that case.\n\n This is how the new trailer is added: a `=`\n or `:` argument given using `--trailer` will be appended\n after the existing trailers. The __ and __ parts will be\n trimmed to remove starting and trailing whitespace, and the resulting\n trimmed __ and __ will appear in the output like this:\n\nAnd it still flows.\n\n>\n>> ------------------------------------------------\n>> key: value\n>> @@ -74,6 +82,16 @@ key: value\n>> This means that the trimmed __ and __ will be separated by\n>> \"`:`{nbsp}\" (one colon followed by one space).\n>>\n>> +Existing trailers are extracted from the input by looking for the\n>> +trailer block. Concretely, that is a group of one or more lines that (i)\n>\n> \"Concretely, that is a\" -> \"A trailer block is a\".\n\nYeah. That seems simpler.\n\nReplacing “that” with what it represents, namely “A trailer block”.\n\nSometimes just repeating the noun can feel stuttery, like the sentences\ndon’t flow. But there is enough variation here; the previous sentence\nends with “the trailer block” (definitive), and the next sentence takes\na step back and talks about the indefinitive (a trailer block).\n\n>\n>> +is all trailers, or (ii) contains at least one Git-generated or\n>> +user-configured trailer and consists of at\n>> +least 25% trailers.\n>\n> Hmph, isn't (i) a narrow subset of (ii)?\n\nWell, this text modulo a grammatical fix goes back all the way to the\nimplementation of the 25% rule in 14624506 (trailer: allow non-trailers\nin trailer block, 2016-10-21).\n\nBut I don’t see how either one is a subset of the other. With (i) I just\nneed valid trailers. With (ii) I need at least one “Git-generated”\ntrailer (or `(cherry picked from` I think), i.e. as soon as a\nnon-trailer line has infected the prospective block.\n\nYou could have respectively:\n\ni. Only trailers but none are configured\nii. One configured trailer and one comment line\n\nI don’t see how one can subsume the other.\n\n>\n>> +The trailer block is by definition at the end the the message. The end\n>> +of the message in turn is either (i) at the end of the input, or (ii)\n>\n> \"at the end the the message\" -> \"at the end of the commit log\n> message\", and \"the input\" -> \"the message\", probably.\n\nOkay, there is both a “the the” as well as missing “of”.\n\nAs to “*commit* message”: my first instinct was that the text might as\nwell talk about just “message” throughout, since we establish at the\nbeginning that a commit message is *one* application (and the main one)\nbut isn’t necessarily the only one (tag messages these days, in\nfact). But now I see that we already use “commit message” throughout, so\nit is indeed best to stick with that here.\n\n> The latter is because not everybody is \"parsing\" the message to futz\n> with trailers, using the message as \"input\", and some are \"writing\n> out\" the message, using it as \"output\".\n\nI don’t understand this part. This is supposed to be prosaic. The input\nis the data on the standard input. And of that data the message is a\nsubset, for example and probably most notably with the\ngit-format-patch(1) format.\n\nNow, we could define what “the commit message” is in terms of “the\nmessage”. But those terms are so close, it might look like you are\nrestating “commit message” but just dropping “commit” because it is\nclear from context now.\n\nFor comparison this is the paragraph on `master` (commit 0fae78c9).\n\n Existing trailers are extracted from the input by looking for\n a group of one or more lines that (i) is all trailers, or (ii) contains at\n least one Git-generated or user-configured trailer and consists of at\n least 25% trailers.\n The group must be preceded by one or more empty (or whitespace-only) lines.\n The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with `---` (followed by a\n space or the end of the line).\n\n>> +the last non-whitespace lines before a line that starts with `---`\n>> +(followed by a space or the end of the line).\n>\n> OK.\n"},{"id":"548843","messageId":"xmqqzezhb73q.fsf@gitster.g","threadId":"63233","inReplyTo":"729baf6b-53ea-4e8d-95ab-5935667e66c2@app.fastmail.com","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-23T23:48:25Z","receivedAt":"2026-07-23T23:48:27Z","isPatch":true,"body":"\"Kristoffer Haugsbakk\" writes:\n\nI was reviewing the draft of the What's Cooking report and noticed \nthat this topic is among a handful of stalled efforts going nowhere.\n\n>> If you want to stress that a line with only whitespaces on it does\n>> not count as a blank line for the purpose of this paragraph, you can\n>> consistently say \"an empty line\" withotu saying \"a blank line\", and\n>> you do not need to have \"(specifically an empty lline)\" there.\n>\n> Okay, I’ll make it shorter.\n>\n> It felt too long for a simple concept indeed.\n> ...\n\nAnd it has been more than a month since we discussed this topic the\nlast time. Will we see an update anytime soon? If not, let me\nmark the topic to be discarded in my draft of the whats-cooking\nreport.\n\n\n"},{"id":"549266","messageId":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","threadId":"63233","inReplyTo":"CV_doc_int-tr_key_format.533@msgid.xyz","subject":"[PATCH v4 00/11] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:13Z","receivedAt":"2026-07-30T09:18:48Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-trailers\n\nTopic summary: Explain the format of trailer keys (alphanum and\nhyphens). This is important to keep in mind so that metadata is not\nlost to simple syntax errors. Also replace some terms and define the\nimportant ones upfront.\n\nHere one change lead to another in order to make sure that everything\nstayed coherent. So here’s a linear overview of the changes (as of v4):\n\n• Patches 1–3: remove RFC 822 mentions, “metadata” term\n• Patch 4: This command is not just for commit messages\n• Patches 5–7: Explain the format in the simplest case, explain\n the “key” format, and add a new example\n• Patch 8: join some existing paragraphs that are about the same theme\n since that makes the text flow better\n• Patch 9: Also use the “trailer block” term introduced to the doc in\n patch 5 later in the doc\n• Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)\n• Patch 11: document line comment behavior\n\nThanks to everyone who has been reviewing these so far. I understand that\nthese eleven changes are very incremental and piecemeal (see “very\ncross-referenced commit messages”). And the commit messages can be quite\nlong, just to explain (again) very small changes. See for example patch\n“replace “lines” with “metadata”” in this version, where I explain why to\nwrite “trailer metadata” instead of “trailers metadata”. But right now I\nfeel like prose sometimes needs all this ceremony. With code you get\nrestraints like coding style, then you have all the years of looser rules\nabout when to use certain data structures, when to make helper methods,\netc. But with prose it seems that you bring much more of your individuality\nto it. That means more choices, and many of them are not obvious to the\nreader of the document, which means that you need to explain it in the\ncommit message. Then you also have to consider the writing history of the\ndocument, and this one is twelve years old at this point; see the history\nreview in commit message “join new-trailers again”, after the thematic\nbreak (***).\n\n§ Changes in v4\n\nSee the patch Notes for details. Some minor things might not be mentioned\nhere. But they are all mentioned on the patch Notes.\n\nPatch “add key format example”: fix doubled “to”.\n\nPatch “commit to “trailer block” term”: simplify “blank line” mention a\nlittle bit. But I might need some feedback from Junio on whether I\ninterpreted his comment correctly. There are detailed notes on the patch.\n\nAlso follow up on other copy editing feedback from Junio.[1] Note the\nthings that I didn’t follow up on because I disagreed or didn’t understand.\n\nPatch “rewrite new-trailers paragraphs”: copy editing feedback from Junio.\n\nPatch “replace “lines” with “metadata””: use “trailer metadata”. Suggested\nby Matt Hunter. It reads better.\n\nPatch “document comment line treatment”: rewrite motivation for documenting\nhow comment lines are treated.\n\n🔗 1: https://lore.kernel.org/git/729baf6b-53ea-4e8d-95ab-5935667e66c2@app.fastmail.com/\n\n§ Apologies for very cross-referenced commit messages\n\n(see v3)\n\n§ Cc\n\n(see v2)\n\nhttps://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/\n\n§ In-reply-to: v1\n\nThe recommendation to reply to the first version/cover letter is from topic\nps/doc-recommend-b4, which is in `next` right now.\n\n§ Link to v3\n\nhttps://lore.kernel.org/git/V3_CV_doc_int-tr_key_format.8a3@msgid.xyz/\n\n[01/11] doc: interpret-trailers: stop fixating on RFC 822\n[02/11] doc: interpret-trailers: replace “lines” with “metadata”\n[03/11] doc: interpret-trailers: use “metadata” in Name as well\n[04/11] doc: interpret-trailers: not just for commit messages\n[05/11] doc: interpret-trailers: explain the format after the intro\n[06/11] doc: interpret-trailers: explain key format\n[07/11] doc: interpret-trailers: add key format example\n[08/11] doc: interpret-trailers: join new-trailers again\n[09/11] doc: interpret-trailers: commit to “trailer block” term\n[10/11] doc: interpret-trailers: rewrite new-trailers paragraphs\n[11/11] doc: interpret-trailers: document comment line treatment\n\n Documentation/git-interpret-trailers.adoc | 88 ++++++++++++++++-------\n 1 file changed, 64 insertions(+), 24 deletions(-)\n\nInterdiff against v3:\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex d5e856f5d68..b4988d39eab 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse trailers metadata at the end of the otherwise\n+Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n \n A _trailer_ in its simplest form is a key-value pair with a colon as a\n@@ -66,14 +66,14 @@ Also by default, this new trailer will only be added\n if the last trailer is different to it.\n A trailer block will be created with only that trailer if a trailer\n block does not already exist. Recall that a trailer block needs to be\n-preceded by a blank line, so a blank line (specifically an empty line)\n-will be inserted before the new trailer block in that case.\n+preceded by a blank line, so a blank line will be inserted before the\n+new trailer block in that case.\n \n-More concretely, this is how the new trailer is added: a `=`\n-or `:` argument given using `--trailer` will be appended\n-after the existing trailers. The __ and __ parts will be\n-trimmed to remove starting and trailing whitespace, and the resulting\n-trimmed __ and __ will appear in the output like this:\n+This is how the new trailer is added: a `=` or\n+`:` argument given using `--trailer` will be appended after\n+the existing trailers. The __ and __ parts will be trimmed\n+to remove starting and trailing whitespace, and the resulting trimmed\n+__ and __ will appear in the output like this:\n \n ------------------------------------------------\n key: value\n@@ -83,14 +83,14 @@ This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n Existing trailers are extracted from the input by looking for the\n-trailer block. Concretely, that is a group of one or more lines that (i)\n+trailer block. A trailer block is a group of one or more lines that (i)\n is all trailers, or (ii) contains at least one Git-generated or\n user-configured trailer and consists of at\n least 25% trailers.\n-The trailer block is by definition at the end the the message. The end\n-of the message in turn is either (i) at the end of the input, or (ii)\n-the last non-whitespace lines before a line that starts with `---`\n-(followed by a space or the end of the line).\n+The trailer block is by definition at the end of the commit message.\n+The message in turn is either (i) at the end of the input, or (ii) the\n+last non-whitespace lines before a line that starts with `---` (followed\n+by a space or the end of the line).\n \n For convenience, a __ can be configured to make using `--trailer`\n shorter to type on the command line. This can be configured using the\n@@ -419,8 +419,8 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n-* Here we try to to use three different trailer keys. But it fails\n- because two of them are not recognized as trailer keys.\n+* Here we try to use three different trailer keys. But it fails because\n+ two of them are not recognized as trailer keys.\n +\n ----\n $ cat msg.txt\nRange-diff against v3:\n 1: e5d58237bc2 ! 1: 2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822\n @@ Metadata\n ## Commit message ##\n doc: interpret-trailers: stop fixating on RFC 822\n \n - This command handles the trailers metadata format. But the command\n + This command handles the trailer metadata format. But the command\n isn’t introduced as such; it is instead introduced by stating that\n these trailer lines look similar to RFC 822 email headers.\n \n 2: 5ddd39bf157 ! 2: 859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata”\n @@ Commit message\n \n † 1: 68e3c69e (Documentation/glossary: describe \"trailer\", 2024-11-17)\n \n + Let’s not emphasize “trailer” here since we are going to define the term\n + in the upcoming commit “explain the format after the intro”.\n +\n + Let’s call it “trailer metadata” rather than “trailers metadata”.\n + At first it seemed better to use the latter:\n +\n + 1. We’re introducing the jargon, and the format is often discussed as\n + plural “trailers”, with its constituent parts being singular\n + “trailer”\n + 2. What this replaces uses “trailer”, but it rescues the plural mood\n + with “lines”\n + 3. This is very soon going to go into the constituent parts, including\n + each trailer, so we’re contrasting the concept name (trailers) with\n + its parts\n +\n + But:\n +\n + 1. The former reads better (most important)\n + 2. “Trailer *metadata*” suggests plurality, similar to “trailer *lines*”\n +\n + Helped-by: Matt Hunter \n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-interpret-trailers.adoc ##\n @@ Documentation/git-interpret-trailers.adoc: git interpret-trailers [--in-place] [\n DESCRIPTION\n -----------\n -Add or parse _trailer_ lines at the end of the otherwise\n -+Add or parse trailers metadata at the end of the otherwise\n ++Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message. For example, in the following commit\n message\n \n 3: 9f0227a1978 ! 3: ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well\n @@ Metadata\n ## Commit message ##\n doc: interpret-trailers: use “metadata” in Name as well\n \n - We now since the previous commit introduce the format as “trailers\n + We now since the previous commit introduce the format as “trailer\n metadata”. We can replace “structured information” with “metadata”\n in the “Name” section to be consistent.\n \n 4: 4cb26810d4e ! 4: b79ddf3b13e doc: interpret-trailers: not just for commit messages\n @@ Documentation/git-interpret-trailers.adoc\n @@ Documentation/git-interpret-trailers.adoc: git interpret-trailers [--in-place] [--trim-empty]\n DESCRIPTION\n -----------\n - Add or parse trailers metadata at the end of the otherwise\n + Add or parse trailer metadata at the end of the otherwise\n -free-form part of a commit message. For example, in the following commit\n -message\n +free-form part of a commit message, or any other kind of text.\n 5: 196c91bebe3 ! 5: e7101eb1fcb doc: interpret-trailers: explain the format after the intro\n @@ Commit message\n well as define the most important terms.\n \n Note that we name the “blank line” rule since I want to use that term\n - every time it comes up. It gets very mildly obfuscated if you call it a\n - “blank line” in one place[2] and “empty (or whitespace-only) ...” in\n + every time it comes up. It gets very mildly obfuscated if you call it\n + a “blank line” in one place[2] and “empty (or whitespace-only) ...” in\n another one.[3]\n \n We will define the format of the *key* in the next commit.\n @@ Commit message\n ## Documentation/git-interpret-trailers.adoc ##\n @@ Documentation/git-interpret-trailers.adoc: DESCRIPTION\n -----------\n - Add or parse trailers metadata at the end of the otherwise\n + Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n -For example, in the following commit message\n +\n 6: 688ea55599a ! 6: 557b5b5564a doc: interpret-trailers: explain key format\n @@ Commit message\n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-interpret-trailers.adoc ##\n -@@ Documentation/git-interpret-trailers.adoc: Add or parse trailers metadata at the end of the otherwise\n +@@ Documentation/git-interpret-trailers.adoc: Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n \n A _trailer_ in its simplest form is a key-value pair with a colon as a\n 7: e6eafbd641f ! 7: eee81fc99fa doc: interpret-trailers: add key format example\n @@ Documentation/git-interpret-trailers.adoc: mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n -+* Here we try to to use three different trailer keys. But it fails\n -+ because two of them are not recognized as trailer keys.\n ++* Here we try to use three different trailer keys. But it fails because\n ++ two of them are not recognized as trailer keys.\n ++\n +----\n +$ cat msg.txt\n 8: 8849ace33e6 ! 8: cd3e47459c7 doc: interpret-trailers: join new-trailers again\n @@ Metadata\n ## Commit message ##\n doc: interpret-trailers: join new-trailers again\n \n - There are three trailers that talk about how a new trailer is added.\n + There are three paragraphs that talk about how a new trailer is added.\n But the first one is separated from the other two by two paragraphs\n about how `key-alias` can make using `--trailer` more convenient. This\n short how-to does not follow thematically from the previous paragraph,\n 9: 8323b84e134 ! 9: c50b6d25170 doc: interpret-trailers: commit to “trailer block” term\n @@ Commit message\n invented term.\n \n That term was useful to explain where the trailers are found (they\n - *trail* the message). But it is also useful here, where we explain how\n - trailers are added to existing messages, how trailer blocks are\n - found (beyond the simple case in the introduction), and how the end of\n - the message is found.\n + *trail* the message). But it is also useful here, where we explain\n + how trailers are added to existing messages, how trailer blocks are\n + found (beyond the simple case in the introduction), and how the end\n + of the message is found.\n +\n + Also note that we simplify the “blank line” point. The text says:\n +\n + A blank line will be added before the new trailer if there isn't one\n + already.\n +\n + But this isn’t quite coherent. The previous sentence says “If there is\n + no existing trailer”, so we are in one of these modes:\n +\n + 1. discussing trailer blocks in general; or\n + 2. discussing creating a new trailer block in particular.\n +\n + If (1), then we shouldn’t add a blank line before the new trailer if\n + there exists a trailer block already. And if (2), then the “if there\n + isn’t one already” is redundant.[2] So just talking about the higher-\n + level “trailer block” simplifies the text, since we don’t have to worry\n + about the different contexts that *trailers* can find themselves in.\n \n † 1: in commit “explain the format after the intro”\n + † 2: Note that non-trailer lines don’t matter here; if you have a\n + trailer block consisting of `(cherry picked from commit )`,\n + then you still shouldn’t insert a blank line before the new trailer\n + since that would create a new trailer block\n \n Signed-off-by: Kristoffer Haugsbakk \n \n @@ Documentation/git-interpret-trailers.adoc: key: value\n +By default the new trailer will appear at the end of the trailer block.\n +A trailer block will be created with only that trailer if a trailer\n +block does not already exist. Recall that a trailer block needs to be\n -+preceded by a blank line, so a blank line (specifically an empty line)\n -+will be inserted before the new trailer block in that case.\n ++preceded by a blank line, so a blank line will be inserted before the\n ++new trailer block in that case.\n +\n +Existing trailers are extracted from the input by looking for the\n -+trailer block. Concretely, that is a group of one or more lines that (i)\n ++trailer block. A trailer block is a group of one or more lines that (i)\n +is all trailers, or (ii) contains at least one Git-generated or\n +user-configured trailer and consists of at\n least 25% trailers.\n @@ Documentation/git-interpret-trailers.adoc: key: value\n -The group must either be at the end of the input or be the last\n -non-whitespace lines before a line that starts with `---` (followed by a\n -space or the end of the line).\n -+The trailer block is by definition at the end the the message. The end\n -+of the message in turn is either (i) at the end of the input, or (ii)\n -+the last non-whitespace lines before a line that starts with `---`\n -+(followed by a space or the end of the line).\n ++The trailer block is by definition at the end of the commit message.\n ++The message in turn is either (i) at the end of the input, or (ii) the\n ++last non-whitespace lines before a line that starts with `---` (followed\n ++by a space or the end of the line).\n \n For convenience, a __ can be configured to make using `--trailer`\n shorter to type on the command line. This can be configured using the\n10: c7495c3b39e ! 10: c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs\n @@ Commit message\n 1. Declare that we are about to talk about `--trailer` appending\n 2. Explain the default behavior\n 3. Explain how this affects the trailer block\n - 4. Then state the same thing (“More concretely”) in concrete terms with\n - placeholders\n + 4. Then discuss what each trailer line will look like\n \n Signed-off-by: Kristoffer Haugsbakk \n \n @@ Documentation/git-interpret-trailers.adoc: are applied to each input and the way\n -using `--trailer` will be appended after the existing trailers only if\n -the last trailer has a different (__, __) pair (or if there\n -is no existing trailer). The __ and __ parts will be trimmed\n --to remove starting and trailing whitespace, and the resulting trimmed\n --__ and __ will appear in the output like this:\n +Let's consider new trailers added with `--trailer`.\n +By default, the new trailer will appear at the end of the trailer block.\n +Also by default, this new trailer will only be added\n +if the last trailer is different to it.\n +A trailer block will be created with only that trailer if a trailer\n +block does not already exist. Recall that a trailer block needs to be\n -+preceded by a blank line, so a blank line (specifically an empty line)\n -+will be inserted before the new trailer block in that case.\n ++preceded by a blank line, so a blank line will be inserted before the\n ++new trailer block in that case.\n +\n -+More concretely, this is how the new trailer is added: a `=`\n -+or `:` argument given using `--trailer` will be appended\n -+after the existing trailers. The __ and __ parts will be\n -+trimmed to remove starting and trailing whitespace, and the resulting\n -+trimmed __ and __ will appear in the output like this:\n ++This is how the new trailer is added: a `=` or\n ++`:` argument given using `--trailer` will be appended after\n ++the existing trailers. The __ and __ parts will be trimmed\n + to remove starting and trailing whitespace, and the resulting trimmed\n + __ and __ will appear in the output like this:\n \n - ------------------------------------------------\n - key: value\n @@ Documentation/git-interpret-trailers.adoc: key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n @@ Documentation/git-interpret-trailers.adoc: key: value\n -By default the new trailer will appear at the end of the trailer block.\n -A trailer block will be created with only that trailer if a trailer\n -block does not already exist. Recall that a trailer block needs to be\n --preceded by a blank line, so a blank line (specifically an empty line)\n --will be inserted before the new trailer block in that case.\n +-preceded by a blank line, so a blank line will be inserted before the\n +-new trailer block in that case.\n -\n Existing trailers are extracted from the input by looking for the\n - trailer block. Concretely, that is a group of one or more lines that (i)\n + trailer block. A trailer block is a group of one or more lines that (i)\n is all trailers, or (ii) contains at least one Git-generated or\n11: fc38e8660f0 ! 11: 7d20cb7528f doc: interpret-trailers: document comment line treatment\n @@ Commit message\n \n Comment lines have always been ignored but this is not documented.\n \n - This is mostly for completeness since this is unlikely to catch anyone\n - by surprise. But we really ought to be reasonably complete here since\n - it’s the only documentation page that documents trailers.\n + The primary motivation here is to reasonably complete in the\n + documentation of how trailers are parsed; this is after all the only\n + documentation page that documents this format. However, and going beyond\n + that point, we could imagine that someone would want to use this format\n + outside a commit (or tag) message context, like say in Git notes.\n +\n + On the other hand, it seems far-fetched that someone would be caught\n + off guard by this considering that comment characters/strings are not\n + likely to be alphanumeric,[1] which would mean that these comment lines\n + would be treated as non-trailer lines if they were *not* detected and\n + removed as comment lines.\n +\n + † 1: A notable exception is that Jujutsu VCS uses `JJ:` as\n + the comment string\n \n Signed-off-by: Kristoffer Haugsbakk \n \n\nbase-commit: 5361983c075154725be47b65cca9a2421789e410\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549267","messageId":"V4_less_RFC_822_focus.ae3@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 01/11] doc: interpret-trailers: stop fixating on RFC 822","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:14Z","receivedAt":"2026-07-30T09:19:07Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command handles the trailer metadata format. But the command\nisn’t introduced as such; it is instead introduced by stating that\nthese trailer lines look similar to RFC 822 email headers.\n\nThis is overwrought; most people do not deal directly with email\nheaders, and certainly not email RFCs.\n\nTrailers are just key–value pairs that, like email headers, use colon\nas the separator. The format in its simplest form is easy to describe\ndirectly without comparing it to anything else; we will do that in the\nupcoming commit “explain the format after the intro”.\n\nFor now, let’s:\n\n• remove the first mention of email headers;\n• keep the second, innocuous comparison with email line folding in the\n middle; and\n• remove the now-unneeded disclaimer that trailers do not share many of\n the features of RFC 822 email headers—there is no invitation to\n speculate that trailers would follow any other email format rules\n since we do not compare them directly any more.\n\n***\n\nTalking about trailers as an RFC 822/2822-like format seems to go back\nto the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated\nthis command and in turn the first trailer support in git(1) beyond\nadding s-o-b lines.\n\n† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: s/trailers metadata/trailer metadata/ (knock-on effect from\n change in the *next* commit)\n \n ---\n \n v2:\n • Use `***` as a thematic break instead of `❦`\n • Change to “metadata” instead of “key–value pairs” since this series\n version adds a paragraph after this one where we dig into this\n term. And “metadata” describes the purpose of this format.\n\n Documentation/git-interpret-trailers.adoc | 9 +++------\n 1 file changed, 3 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 77b4f63b05c..1878848ad2a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n-headers, at the end of the otherwise free-form part of a commit\n-message. For example, in the following commit message\n+Add or parse _trailer_ lines at the end of the otherwise\n+free-form part of a commit message. For example, in the following commit\n+message\n \n ------------------------------------------------\n subject\n@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n-Note that trailers do not follow (nor are they intended to follow) many of the\n-rules for RFC 822 headers. For example they do not follow the encoding rule.\n-\n OPTIONS\n -------\n `--in-place`::\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549268","messageId":"V4_metadata_not_lines.ae4@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 02/11] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:15Z","receivedAt":"2026-07-30T09:19:26Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe removed the initial comparison to email headers in the previous\ncommit. Now the introduction paragraph just says “trailer lines”, and\nthe only hint that this is metadata/structured information is the\n“otherwise free-form” phrase.\n\nLet’s replace “lines” with “metadata” since that is their purpose.\nThis also makes the introduction more consistent with how I chose\nto define trailers in the glossary:[1] “Key-value metadata”. (We will\nintroduce “key–value” in the upcoming commit “explain the format after\nthe intro”.)\n\n† 1: 68e3c69e (Documentation/glossary: describe \"trailer\", 2024-11-17)\n\nLet’s not emphasize “trailer” here since we are going to define the term\nin the upcoming commit “explain the format after the intro”.\n\nLet’s call it “trailer metadata” rather than “trailers metadata”.\nAt first it seemed better to use the latter:\n\n1. We’re introducing the jargon, and the format is often discussed as\n plural “trailers”, with its constituent parts being singular\n “trailer”\n2. What this replaces uses “trailer”, but it rescues the plural mood\n with “lines”\n3. This is very soon going to go into the constituent parts, including\n each trailer, so we’re contrasting the concept name (trailers) with\n its parts\n\nBut:\n\n1. The former reads better (most important)\n2. “Trailer *metadata*” suggests plurality, similar to “trailer *lines*”\n\nHelped-by: Matt Hunter \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • s/trailers metadata/trailer metadata/ since it reads better (and\n see commit message for details)\n \n 🔗 https://lore.kernel.org/git/DJ5W2I8UYXAA.3O4JQUHFMKP5X@lfurio.us/\n • Msg: Add a paragraph to explain why we remove the emphasis from\n “trailer”. In the previous version we replaced “trailer” with\n “trailers”, so we didn’t need to explain it then.\n \n ---\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 1878848ad2a..c8950d3babc 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines at the end of the otherwise\n+Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message. For example, in the following commit\n message\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549269","messageId":"V4_metadata_Name_section.ae5@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 03/11] doc: interpret-trailers: use “metadata” in Name as well","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:16Z","receivedAt":"2026-07-30T09:19:44Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe now since the previous commit introduce the format as “trailer\nmetadata”. We can replace “structured information” with “metadata”\nin the “Name” section to be consistent.\n\nWhile “structured information” does emphasize that the data is not\nloosely structured, we also say that this command adds to or parses\nthis format. I don’t think that we need to emphasize that it is\nstructured since clearly there is some structure there.\n\nBoth “metadata” and “structured information” can convey the same\ninformation. But “metadata” is shorter and easier to deploy since\nit’s just one word.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: s/trailers metadata/trailer metadata/ (knock-on effect from\n change in the prevoius commit)\n \n ---\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex c8950d3babc..5e776f0059a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -3,7 +3,7 @@ git-interpret-trailers(1)\n \n NAME\n ----\n-git-interpret-trailers - Add or parse structured information in commit messages\n+git-interpret-trailers - Add or parse metadata in commit messages\n \n SYNOPSIS\n --------\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549270","messageId":"V4_cmt_msg_or_other_texts.ae6@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 04/11] doc: interpret-trailers: not just for commit messages","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:17Z","receivedAt":"2026-07-30T09:20:03Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command doesn’t interface with commits directly. You can\ninterpret or modify any kind of text, even though commit messages\nare the most relevant.\n\nThe git(1) suite also isn’t restricted to only direct commit support\nsince git-tag(1) learned `--trailer` in 066cef77 (builtin/tag: add\n--trailer option, 2024-05-05)\n\nNow, we already introduce the command in the “Name” section as dealing\nwith commit messages as well. That is fine since that intro line needs\nto remain pretty short.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 5e776f0059a..ab3627c2cba 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty]\n DESCRIPTION\n -----------\n Add or parse trailer metadata at the end of the otherwise\n-free-form part of a commit message. For example, in the following commit\n-message\n+free-form part of a commit message, or any other kind of text.\n+For example, in the following commit message\n \n ------------------------------------------------\n subject\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549271","messageId":"V4_trailer_explain_format.ae7@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 05/11] doc: interpret-trailers: explain the format after the intro","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:18Z","receivedAt":"2026-07-30T09:20:22Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nYou need to read the entire “Description” section in order to understand\nthe full trailer format. But there are many nuances, so that’s fine.\nAs a starter though we have an introductory example.[1] That turns out\nto be crucial; the rest of this section talks about the mechanics of the\ncommand and only incidentally the format itself.\n\nNow, although the example might arguably be self-explanatory, we can\nadd a little preamble which defines the format in its simplest form as\nwell as define the most important terms.\n\nNote that we name the “blank line” rule since I want to use that term\nevery time it comes up. It gets very mildly obfuscated if you call it\na “blank line” in one place[2] and “empty (or whitespace-only) ...” in\nanother one.[3]\n\nWe will define the format of the *key* in the next commit.\n\n† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,\n 2023-06-15)\n† 2: `Documentation/git-interpret-trailers.adoc:86` in\n 5361983c (The 22nd batch, 2026-03-27)\n† 3: `Documentation/git-interpret-trailers.adoc:93` in\n 5361983c (The 22nd batch, 2026-03-27)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4: Msg: reflow paragraph\n \n v2: [new]\n • PS: Suggested here: https://lore.kernel.org/git/8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com/#t\n • (My tardiness on this topic has made these reminders necessary,\n if only for my own reference)\n\n Documentation/git-interpret-trailers.adoc | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex ab3627c2cba..109059f11ed 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -16,7 +16,12 @@ DESCRIPTION\n -----------\n Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n-For example, in the following commit message\n+\n+A _trailer_ in its simplest form is a key-value pair with a colon as a\n+separator. A _trailer block_ consists of one or more trailers. The\n+trailer block needs to be preceded by a blank line, where a _blank line_\n+is either an empty or a whitespace-only line. For example, in the\n+following commit message\n \n ------------------------------------------------\n subject\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549272","messageId":"V4_trailer_key_format.ae8@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 06/11] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:19Z","receivedAt":"2026-07-30T09:20:40Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nA trailer key must consist of ASCII alphanumeric characters and\nhyphens *only*. Let’s document it explicitly instead of relying on\nreaders being conservative and only basing their trailer keys on the\ndocumentation examples.[1]\n\nThe previous commit provided us with an appropriate paragraph to\ndescribe the key format.\n\n† 1: Technically they would then miss out on using digits in them since\n all of the example keys just use letters and hyphens\n\nReported-by: Brendan Jackman \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/\n • Remove the “paint by numbers” reference after review (unclear)\n • Add apropos footnote\n • Tweak the paragraph about how we now have a context to describe\n this format\n v1: [had a note about code spelunking (isalnum(3))]\n\n Documentation/git-interpret-trailers.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 109059f11ed..fb503cbe952 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -18,7 +18,8 @@ Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n \n A _trailer_ in its simplest form is a key-value pair with a colon as a\n-separator. A _trailer block_ consists of one or more trailers. The\n+separator. The _key_ consists of ASCII alphanumeric characters and\n+hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n trailer block needs to be preceded by a blank line, where a _blank line_\n is either an empty or a whitespace-only line. For example, in the\n following commit message\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549273","messageId":"21339fd9-9fcf-46ea-8896-9fde56cd1f29@app.fastmail.com","threadId":"63233","inReplyTo":"xmqqzezhb73q.fsf@gitster.g","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:20:21Z","receivedAt":"2026-07-30T09:20:42Z","isPatch":true,"body":"On Fri, Jul 24, 2026, at 01:48, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>\n> I was reviewing the draft of the What's Cooking report and noticed\n> that this topic is among a handful of stalled efforts going nowhere.\n>\n>>> If you want to stress that a line with only whitespaces on it does\n>>> not count as a blank line for the purpose of this paragraph, you can\n>>> consistently say \"an empty line\" withotu saying \"a blank line\", and\n>>> you do not need to have \"(specifically an empty lline)\" there.\n>>\n>> Okay, I’ll make it shorter.\n>>\n>> It felt too long for a simple concept indeed.\n>> ...\n>\n> And it has been more than a month since we discussed this topic the\n> last time. Will we see an update anytime soon? If not, let me\n> mark the topic to be discarded in my draft of the whats-cooking\n> report.\n\nI’ve posted the next version now.\n"},{"id":"549274","messageId":"V4_trailer_key_format_example.ae9@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 07/11] doc: interpret-trailers: add key format example","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:20Z","receivedAt":"2026-07-30T09:20:59Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nAll of the examples speak of the Happy Path where everything works\nas intended. But failure examples can also be instructive. Especially\nfor explaining again, by example, the key format (see previous commit).\n\nThis also allows us to demonstrate trailer block detection with a\nconcrete example.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4: Fix doubled word “to to”\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++\n 1 file changed, 23 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex fb503cbe952..a0f7ed6fdd9 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -405,6 +405,29 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n+* Here we try to use three different trailer keys. But it fails because\n+ two of them are not recognized as trailer keys.\n++\n+----\n+$ cat msg.txt\n+subject\n+\n+Skapad-på: some-branch\n+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n+Reviewed-by: Alice \n+$ git interpret-trailers --only-trailers \n\nThere are three paragraphs that talk about how a new trailer is added.\nBut the first one is separated from the other two by two paragraphs\nabout how `key-alias` can make using `--trailer` more convenient. This\nshort how-to does not follow thematically from the previous paragraph,\nand can wait until we have fully described how a new trailer is\nadded. So let’s move the three paragraphs about the new-trailer topic\ntogether and move the how-to paragraphs after that.\n\n***\n\nLet’s now review the history of the document. Even if the document\nis not quite correct in its current state, just doing the apparently\nobvious edit without considering the history does not respect the\neffort that went into changing the document in the past.\n\nThese three paragraphs were originally next to each other, in the first\nversion of the doc.[1] But extra sentences about this how-to topic was\nadded to the first paragraph nine years later:[2]\n\n [...]\n `': '` (one colon followed by one space). For convenience, the\n can be a shortened string key (e.g., \"sign\") instead of the\n full string which should [...]\n\nAnd then it was split into it’s own paragraph a little later.[3]\n\nThis evolution shows, in my opinion, that this how-to never followed\nthematically from the existing topic. Which means that there is nothing\nthat was potentially lost to time that we need to restore or respect.\n\n† 1: dfd66ddf (Documentation: add documentation for 'git\n interpret-trailers', 2014-10-13)\n† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)\n† 3: 6ccbc667 (trailer doc: is a or , not both,\n 2023-09-07)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: Fix word-confusion: s/There are three trailers/There are\n three paragraphs.\n \n 🔗 https://lore.kernel.org/git/CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com/\n \n I knew that I was going to fix this when I started on\n version 4. But you would not believe how many times I\n went over the commit log without seeing that I had\n neglected to do this part.\n \n ---\n \n v3: [new]\n • Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/\n • Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]\n \n 🔗 1: https://lore.kernel.org/git/xmqqpl1zsv8s.fsf@gitster.g/\n\n Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex a0f7ed6fdd9..616f479a367 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -74,19 +74,6 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-For convenience, a __ can be configured to make using `--trailer`\n-shorter to type on the command line. This can be configured using the\n-`trailer..key` configuration variable. The __ must be a prefix\n-of the full __ string, although case sensitivity does not matter. For\n-example, if you have\n-\n-------------------------------------------------\n-trailer.sign.key \"Signed-off-by: \"\n-------------------------------------------------\n-\n-in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n-on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n-\n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n at the end of the input. A blank line will be added before the new\n@@ -101,6 +88,19 @@ The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with `---` (followed by a\n space or the end of the line).\n \n+For convenience, a __ can be configured to make using `--trailer`\n+shorter to type on the command line. This can be configured using the\n+`trailer..key` configuration variable. The __ must be a prefix\n+of the full __ string, although case sensitivity does not matter. For\n+example, if you have\n+\n+------------------------------------------------\n+trailer.sign.key \"Signed-off-by: \"\n+------------------------------------------------\n+\n+in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n+on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n+\n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n between the __ and the separator. There can be whitespaces before,\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549276","messageId":"V4_trailer_block_term.aeb@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 09/11] doc: interpret-trailers: commit to “trailer block” term","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:22Z","receivedAt":"2026-07-30T09:21:36Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe chose to introduce the term “trailer block” into the documentation a\nfew commits ago.[1] It is used in the code though, so it is not a newly\ninvented term.\n\nThat term was useful to explain where the trailers are found (they\n*trail* the message). But it is also useful here, where we explain\nhow trailers are added to existing messages, how trailer blocks are\nfound (beyond the simple case in the introduction), and how the end\nof the message is found.\n\nAlso note that we simplify the “blank line” point. The text says:\n\n A blank line will be added before the new trailer if there isn't one\n already.\n\nBut this isn’t quite coherent. The previous sentence says “If there is\nno existing trailer”, so we are in one of these modes:\n\n1. discussing trailer blocks in general; or\n2. discussing creating a new trailer block in particular.\n\nIf (1), then we shouldn’t add a blank line before the new trailer if\nthere exists a trailer block already. And if (2), then the “if there\nisn’t one already” is redundant.[2] So just talking about the higher-\nlevel “trailer block” simplifies the text, since we don’t have to worry\nabout the different contexts that *trailers* can find themselves in.\n\n† 1: in commit “explain the format after the intro”\n† 2: Note that non-trailer lines don’t matter here; if you have a\n trailer block consisting of `(cherry picked from commit )`,\n then you still shouldn’t insert a blank line before the new trailer\n since that would create a new trailer block\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Tweak “blank line” reminder (“Recall that”) by dropping\n “specifically” since it is redundant based on [1]. Well, I\n thought I understood the feedback here but reading it again\n today I was confused. @Junio, did I understand it correctly?\n \n My thought process: This “recall that” is similar to other\n “recall” phrases added in the series. They add some redundancy,\n similar in spirit to 74522b6b (Documentation/git-update-ref.txt:\n discuss symbolic refs, 2024-10-21) :\n \n | Add a paragraph which just emphasizes that the command without\n | any options does not support refs in the final arguments. This\n | is clear already from the names `` and `` but\n | the right balance of redundancy makes documentation robust\n | against stray interpretation.\n • Msg: Editing the above I noticed that the previous (before this\n change “blank line” explanation isn’t (quite) coherent. I want to\n explain every meaningful point of change in the commit message, so\n I dedicate some “also” paragraphs to that change.\n • For [1] again: s/Concretely, that/A trailer block/ since it flows\n better\n • For [1] again: Fix mangled “The trailer block is by definition”\n sentence and make sure to use “commit message”. We use “commit\n message” throughout the doc, not just “message”. But just use\n “message” in the next sentence since it is clear that we are\n still talking about *commit* message.\n • Msg: Reflow existing paragraph\n \n 🔗 1: https://lore.kernel.org/git/xmqqcxxyt4op.fsf@gitster.g/#t\n \n ---\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------\n 1 file changed, 14 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 616f479a367..a1adab20fef 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -74,19 +74,21 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-By default the new trailer will appear at the end of all the existing\n-trailers. If there is no existing trailer, the new trailer will appear\n-at the end of the input. A blank line will be added before the new\n-trailer if there isn't one already.\n-\n-Existing trailers are extracted from the input by looking for\n-a group of one or more lines that (i) is all trailers, or (ii) contains at\n-least one Git-generated or user-configured trailer and consists of at\n+By default the new trailer will appear at the end of the trailer block.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line will be inserted before the\n+new trailer block in that case.\n+\n+Existing trailers are extracted from the input by looking for the\n+trailer block. A trailer block is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n least 25% trailers.\n-The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the input or be the last\n-non-whitespace lines before a line that starts with `---` (followed by a\n-space or the end of the line).\n+The trailer block is by definition at the end of the commit message.\n+The message in turn is either (i) at the end of the input, or (ii) the\n+last non-whitespace lines before a line that starts with `---` (followed\n+by a space or the end of the line).\n \n For convenience, a __ can be configured to make using `--trailer`\n shorter to type on the command line. This can be configured using the\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549277","messageId":"V4_rewrite_new-trailers.aec@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:23Z","receivedAt":"2026-07-30T09:21:55Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTwo commits ago we moved new-trailers paragraph next to each other.\nBut there is something curious about two of them:\n\n By default the new trailer will appear at the end of the trailer\n block. [...]\n\nThen a source block and a paragraph later:\n\n By default, a `=` or `:` argument given\n using `--trailer` will be appended after the existing trailers only\n if [...]\n\nWhy are there two paragraphs that talk about how “By default” a trailer\nwill be appended?\n\nWe can make these paragraphs flow better, and with a more distinct\ncharacter each, by dividing the flow like this:\n\n1. Declare that we are about to talk about `--trailer` appending\n2. Explain the default behavior\n3. Explain how this affects the trailer block\n4. Then discuss what each trailer line will look like\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Simplify “This is how the new trailer” paragraph: drop “More\n concretely,” since it is misleading (this is not a “more\n concretely continuation of the preceding paragraph(s))[1]\n \n 🔗 1: https://lore.kernel.org/git/xmqqcxxyt4op.fsf@gitster.g/\n \n ---\n \n v3: [new]\n • Based on draft: https://lore.kernel.org/git/fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com/\n • See msg:\n \n Two commits ago we moved new-trailers paragraph next to\n each other.\n \n This commit here might fit better one step back. So that it\n becomes the commit right after. But I can deal with that commit\n movement if this change is accepted. For now I didn’t bother.\n\n Documentation/git-interpret-trailers.adoc | 22 ++++++++++++----------\n 1 file changed, 12 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex a1adab20fef..ac59ef51f80 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -60,10 +60,18 @@ are applied to each input and the way any existing trailer in\n the input is changed. They also make it possible to\n automatically add some trailers.\n \n-By default, a `=` or `:` argument given\n-using `--trailer` will be appended after the existing trailers only if\n-the last trailer has a different (__, __) pair (or if there\n-is no existing trailer). The __ and __ parts will be trimmed\n+Let's consider new trailers added with `--trailer`.\n+By default, the new trailer will appear at the end of the trailer block.\n+Also by default, this new trailer will only be added\n+if the last trailer is different to it.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line will be inserted before the\n+new trailer block in that case.\n+\n+This is how the new trailer is added: a `=` or\n+`:` argument given using `--trailer` will be appended after\n+the existing trailers. The __ and __ parts will be trimmed\n to remove starting and trailing whitespace, and the resulting trimmed\n __ and __ will appear in the output like this:\n \n@@ -74,12 +82,6 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-By default the new trailer will appear at the end of the trailer block.\n-A trailer block will be created with only that trailer if a trailer\n-block does not already exist. Recall that a trailer block needs to be\n-preceded by a blank line, so a blank line will be inserted before the\n-new trailer block in that case.\n-\n Existing trailers are extracted from the input by looking for the\n trailer block. A trailer block is a group of one or more lines that (i)\n is all trailers, or (ii) contains at least one Git-generated or\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549278","messageId":"V4_trailer_comment_lines.aed@msgid.xyz","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"[PATCH v4 11/11] doc: interpret-trailers: document comment line treatment","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:18:24Z","receivedAt":"2026-07-30T09:22:13Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nComment lines have always been ignored but this is not documented.\n\nThe primary motivation here is to reasonably complete in the\ndocumentation of how trailers are parsed; this is after all the only\ndocumentation page that documents this format. However, and going beyond\nthat point, we could imagine that someone would want to use this format\noutside a commit (or tag) message context, like say in Git notes.\n\nOn the other hand, it seems far-fetched that someone would be caught\noff guard by this considering that comment characters/strings are not\nlikely to be alphanumeric,[1] which would mean that these comment lines\nwould be treated as non-trailer lines if they were *not* detected and\nremoved as comment lines.\n\n† 1: A notable exception is that Jujutsu VCS uses `JJ:` as\n the comment string\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: rewrite motivation for documenting this. The motivation is\n not super solid, but it reflects my own ambiguity on the matter,\n so to speak; I think we ought to be very thorough about\n documenting the format, while making sure to not use the main text\n to exhaustively lay it all out. The information should be\n somewhere in this doc. But not in your face.\n • Msg: Add “(or tag) message”. See patch “not just for commit\n messages” where trailer support for tag messages are mentioned.\n \n ---\n \n v3:\n • Msg: finally fix area\n • Demote this point to its own “other rules” section, out of the main\n running text. It is not important enough for the main text.\n • Since writing this I have realized that we can go into that long\n \n # ----- >8 ----\n \n Commit message separator scissor line, maybe other things. But I stop\n short here. These things are even less likely to become a problem for\n anyone. And maybe we’ll add them later?\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex ac59ef51f80..b4988d39eab 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n+OTHER RULES\n+-----------\n+\n+What was covered in the previous section are the rules that are relevant\n+for regular use. The following points are included for completeness.\n+\n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n+\n OPTIONS\n -------\n `--in-place`::\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549848","messageId":"CALnO6CB_0ucqnAowrNcPmsXmxxDfJQZPVGkbsHVuya7NLR4dsg@mail.gmail.com","threadId":"63233","inReplyTo":"V4_trailer_comment_lines.aed@msgid.xyz","subject":"Re: [PATCH v4 11/11] doc: interpret-trailers: document comment line treatment","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-08-06T11:52:57Z","receivedAt":"2026-08-06T11:53:09Z","isPatch":true,"body":"Hi Kristoffer,\n\nOn Thu, Jul 30, 2026 at 5:22 AM wrote:\n>\n> From: Kristoffer Haugsbakk \n>\n> Comment lines have always been ignored but this is not documented.\n>\n> The primary motivation here is to reasonably complete in the\n\n\"to be\"?\n\n> documentation of how trailers are parsed; this is after all the only\n> documentation page that documents this format. However, and going beyond\n> that point, we could imagine that someone would want to use this format\n> outside a commit (or tag) message context, like say in Git notes.\n>\n> On the other hand, it seems far-fetched that someone would be caught\n> off guard by this considering that comment characters/strings are not\n> likely to be alphanumeric,[1] which would mean that these comment lines\n> would be treated as non-trailer lines if they were *not* detected and\n> removed as comment lines.\n>\n> † 1: A notable exception is that Jujutsu VCS uses `JJ:` as\n> the comment string\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n>\n> Notes (series):\n> v4:\n> • Msg: rewrite motivation for documenting this. The motivation is\n> not super solid, but it reflects my own ambiguity on the matter,\n> so to speak; I think we ought to be very thorough about\n> documenting the format, while making sure to not use the main text\n> to exhaustively lay it all out. The information should be\n> somewhere in this doc. But not in your face.\n\nI agree we should be thorough but not in your face, esp. based on the\nwork Julia Evans has done in the past around Git documentation.\nThanks!\n\n> • Msg: Add “(or tag) message”. See patch “not just for commit\n> messages” where trailer support for tag messages are mentioned.\n>\n[snip]\n\n-- \nD. Ben Knoble\n"},{"id":"549849","messageId":"CALnO6CAmM4r2uiuBFJcciR_94KPRSJoCOsuNKeqTQ0Bt=Puvyw@mail.gmail.com","threadId":"63233","inReplyTo":"V4_CV_doc_int-tr_key_format.ae2@msgid.xyz","subject":"Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-08-06T11:55:38Z","receivedAt":"2026-08-06T11:55:51Z","isPatch":true,"body":"Hi Kristoffer,\n\nApologies for not returning to this for a while! I haven't read the\nwhole v4 in detail, but I reviewed the final diff and output.\n\nOn Thu, Jul 30, 2026 at 5:18 AM wrote:\n>\n> From: Kristoffer Haugsbakk \n>\n> Topic name (applied): kh/doc-trailers\n>\n> Topic summary: Explain the format of trailer keys (alphanum and\n> hyphens). This is important to keep in mind so that metadata is not\n> lost to simple syntax errors. Also replace some terms and define the\n> important ones upfront.\n>\n> Here one change lead to another in order to make sure that everything\n> stayed coherent. So here’s a linear overview of the changes (as of v4):\n>\n> • Patches 1–3: remove RFC 822 mentions, “metadata” term\n> • Patch 4: This command is not just for commit messages\n\nOne small comment on patch 4\n\n> • Patches 5–7: Explain the format in the simplest case, explain\n> the “key” format, and add a new example\n> • Patch 8: join some existing paragraphs that are about the same theme\n> since that makes the text flow better\n> • Patch 9: Also use the “trailer block” term introduced to the doc in\n> patch 5 later in the doc\n> • Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)\n> • Patch 11: document line comment behavior\n\nA few places we use an inline list syntax (\"… (i) stuff … (ii) more\nstuff …\"). In the added example about ASCII trailers it is useful\nbecause we make reference to (ii); in the initial part of the manual,\nI don't see any references to the delimited items, so I'm not sure if\nit's worth numbering them.\n\nNot a strong statement, though, so I'm happy either way. Everything\nelse (that I looked at, see above) looks good to me.\n\nThanks!\n\n-- \nD. Ben Knoble\n"},{"id":"549880","messageId":"xmqqldajhv9q.fsf@gitster.g","threadId":"63233","inReplyTo":"CALnO6CAmM4r2uiuBFJcciR_94KPRSJoCOsuNKeqTQ0Bt=Puvyw@mail.gmail.com","subject":"Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-08-06T20:02:57Z","receivedAt":"2026-08-06T20:03:00Z","isPatch":true,"body":"\"D. Ben Knoble\" writes:\n\n> One small comment on patch 4\n> ...\n> A few places we use an inline list syntax (\"… (i) stuff … (ii) more\n> stuff …\"). In the added example about ASCII trailers it is useful\n> because we make reference to (ii); in the initial part of the manual,\n> I don't see any references to the delimited items, so I'm not sure if\n> it's worth numbering them.\n>\n> Not a strong statement, though, so I'm happy either way. Everything\n> else (that I looked at, see above) looks good to me.\n\nI guess we are gettng very close to the finish line. Kristoffer,\nhow would we want to proceed?\n\nThanks, both.\n"},{"id":"550107","messageId":"b9cac360-ec97-4715-b176-7850a40ff433@app.fastmail.com","threadId":"63233","inReplyTo":"CALnO6CB_0ucqnAowrNcPmsXmxxDfJQZPVGkbsHVuya7NLR4dsg@mail.gmail.com","subject":"Re: [PATCH v4 11/11] doc: interpret-trailers: document comment line treatment","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-08T19:45:49Z","receivedAt":"2026-08-08T19:46:19Z","isPatch":true,"body":"On Thu, Aug 6, 2026, at 13:52, D. Ben Knoble wrote:\n> Hi Kristoffer,\n>\n> On Thu, Jul 30, 2026 at 5:22 AM wrote:\n>>\n>> From: Kristoffer Haugsbakk \n>>\n>> Comment lines have always been ignored but this is not documented.\n>>\n>> The primary motivation here is to reasonably complete in the\n>\n> \"to be\"?\n\nThanks. I keep staring at the text but in the end you need someone else\nto read it as well.\n\n>>[snip]\n>> Notes (series):\n>> v4:\n>> • Msg: rewrite motivation for documenting this. The motivation is\n>> not super solid, but it reflects my own ambiguity on the matter,\n>> so to speak; I think we ought to be very thorough about\n>> documenting the format, while making sure to not use the main text\n>> to exhaustively lay it all out. The information should be\n>> somewhere in this doc. But not in your face.\n>\n> I agree we should be thorough but not in your face, esp. based on the\n> work Julia Evans has done in the past around Git documentation.\n> Thanks!\n\nThanks. I’m glad that I was able to communicate that. ;)\n\n>\n>>[snip]\n"},{"id":"550108","messageId":"9422d16f-0bf5-42be-9248-38fd3d0f7b1b@app.fastmail.com","threadId":"63233","inReplyTo":"CALnO6CAmM4r2uiuBFJcciR_94KPRSJoCOsuNKeqTQ0Bt=Puvyw@mail.gmail.com","subject":"Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-08T20:01:38Z","receivedAt":"2026-08-08T20:02:03Z","isPatch":true,"body":"On Thu, Aug 6, 2026, at 13:55, D. Ben Knoble wrote:\n> Hi Kristoffer,\n>\n> Apologies for not returning to this for a while! I haven't read the\n> whole v4 in detail, but I reviewed the final diff and output.\n\nYour reviews, in whatever timeframe, are very much appreciated.\n\n> On Thu, Jul 30, 2026 at 5:18 AM wrote:\n>>[snip]\n>\n> A few places we use an inline list syntax (\"… (i) stuff … (ii) more\n> stuff …\"). In the added example about ASCII trailers it is useful\n> because we make reference to (ii); in the initial part of the manual,\n> I don't see any references to the delimited items, so I'm not sure if\n> it's worth numbering them.\n\nI did adopt that Roman numeral inline list style for the example based\non the existing one.\n\nI’ve always read it as a stylistic choice. So not for the ability to\nreference them. You have that ability, but I have the impression that\nmost inline lists like that are not used to reference back to the item.\n\nThis existing inline list goes back long before this series. Changing it\nwould mean adding another change to an already long series. And I’m not\nsure that it should be changed in the first place. So for now at least I\nam not going to pick up on this topic.\n\nI will wait at least a day for any more comments and post a new version\nwith that fix to the commit message.\n\n>\n>[snip]\n"},{"id":"550109","messageId":"d60621cd-79cb-4fac-bc0b-828e29131043@app.fastmail.com","threadId":"63233","inReplyTo":"xmqqldajhv9q.fsf@gitster.g","subject":"Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-08T20:02:47Z","receivedAt":"2026-08-08T20:03:13Z","isPatch":true,"body":"On Thu, Aug 6, 2026, at 22:02, Junio C Hamano wrote:\n> \"D. Ben Knoble\" writes:\n>\n>> One small comment on patch 4\n>> ...\n>> A few places we use an inline list syntax (\"… (i) stuff … (ii) more\n>> stuff …\"). In the added example about ASCII trailers it is useful\n>> because we make reference to (ii); in the initial part of the manual,\n>> I don't see any references to the delimited items, so I'm not sure if\n>> it's worth numbering them.\n>>\n>> Not a strong statement, though, so I'm happy either way. Everything\n>> else (that I looked at, see above) looks good to me.\n>\n> I guess we are gettng very close to the finish line. Kristoffer,\n> how would we want to proceed?\n>\n> Thanks, both.\n\nI will wait at least one day for any more comments and post a new\nversion with that fix that Knoble found to the commit message.\n"},{"id":"550134","messageId":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","threadId":"63233","inReplyTo":"CV_doc_int-tr_key_format.533@msgid.xyz","subject":"[PATCH v5 00/11] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:24Z","receivedAt":"2026-08-09T20:07:15Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-trailers\n\nTopic summary: Explain the format of trailer keys (alphanum and\nhyphens). This is important to keep in mind so that metadata is not\nlost to simple syntax errors. Also replace some terms and define the\nimportant ones upfront.\n\nHere one change lead to another in order to make sure that everything\nstayed coherent. So here’s a linear overview of the changes (as of v4):\n\n• Patches 1–3: remove RFC 822 mentions, “metadata” term\n• Patch 4: This command is not just for commit messages\n• Patches 5–7: Explain the format in the simplest case, explain\n the “key” format, and add a new example\n• Patch 8: join some existing paragraphs that are about the same theme\n since that makes the text flow better\n• Patch 9: Also use the “trailer block” term introduced to the doc in\n patch 5 later in the doc\n• Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)\n• Patch 11: document line comment behavior\n\nThanks to everyone who has been reviewing these so far. I understand that\nthese eleven changes are very incremental and piecemeal (see “very\ncross-referenced commit messages”). And the commit messages can be quite\nlong, just to explain (again) very small changes. See for example patch\n“replace “lines” with “metadata”” in this version, where I explain why to\nwrite “trailer metadata” instead of “trailers metadata”. But right now I\nfeel like prose sometimes needs all this ceremony. With code you get\nrestraints like coding style, then you have all the years of looser rules\nabout when to use certain data structures, when to make helper methods,\netc. But with prose it seems that you bring much more of your individuality\nto it. That means more choices, and many of them are not obvious to the\nreader of the document, which means that you need to explain it in the\ncommit message. Then you also have to consider the writing history of the\ndocument, and this one is twelve years old at this point; see the history\nreview in commit message “join new-trailers again”, after the thematic\nbreak (***).\n\n§ Changes in v5\n\nPatch “document comment line treatment”: commit message: add missing word:\ns/to/to be/.\n\n§ Apologies for very cross-referenced commit messages\n\n(see v3)\n\n§ Cc\n\n(see v2)\n\nhttps://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/\n\nI have also added a new email since the email jackmanb@google.com bounces\nfor me. There is a Brendan Jackman who has posted messages under a Gmail\naddress. Hopefully it’s the same person.\n\n§ In-reply-to: v1\n\nThe recommendation to reply to the first version/cover letter is from topic\nps/doc-recommend-b4, which is in `next` right now.\n\n§ Link to v4\n\nhttps://lore.kernel.org/git/V4_CV_doc_int-tr_key_format.ae2@msgid.xyz/\n\n[01/11] doc: interpret-trailers: stop fixating on RFC 822\n[02/11] doc: interpret-trailers: replace “lines” with “metadata”\n[03/11] doc: interpret-trailers: use “metadata” in Name as well\n[04/11] doc: interpret-trailers: not just for commit messages\n[05/11] doc: interpret-trailers: explain the format after the intro\n[06/11] doc: interpret-trailers: explain key format\n[07/11] doc: interpret-trailers: add key format example\n[08/11] doc: interpret-trailers: join new-trailers again\n[09/11] doc: interpret-trailers: commit to “trailer block” term\n[10/11] doc: interpret-trailers: rewrite new-trailers paragraphs\n[11/11] doc: interpret-trailers: document comment line treatment\n\n Documentation/git-interpret-trailers.adoc | 88 ++++++++++++++++-------\n 1 file changed, 64 insertions(+), 24 deletions(-)\n\nInterdiff against v4:\nRange-diff against v4:\n 1: 2419b1a6863 = 1: 2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822\n 2: 859ab42ac41 = 2: 859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata”\n 3: ab5b4af970e = 3: ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well\n 4: b79ddf3b13e = 4: b79ddf3b13e doc: interpret-trailers: not just for commit messages\n 5: e7101eb1fcb = 5: e7101eb1fcb doc: interpret-trailers: explain the format after the intro\n 6: 557b5b5564a = 6: 557b5b5564a doc: interpret-trailers: explain key format\n 7: eee81fc99fa = 7: eee81fc99fa doc: interpret-trailers: add key format example\n 8: cd3e47459c7 = 8: cd3e47459c7 doc: interpret-trailers: join new-trailers again\n 9: c50b6d25170 = 9: c50b6d25170 doc: interpret-trailers: commit to “trailer block” term\n10: c11a116605e = 10: c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs\n11: 7d20cb7528f ! 11: cabbb05a1c4 doc: interpret-trailers: document comment line treatment\n @@ Commit message\n \n Comment lines have always been ignored but this is not documented.\n \n - The primary motivation here is to reasonably complete in the\n + The primary motivation here is to be reasonably complete in the\n documentation of how trailers are parsed; this is after all the only\n documentation page that documents this format. However, and going beyond\n that point, we could imagine that someone would want to use this format\n\nbase-commit: 5361983c075154725be47b65cca9a2421789e410\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550135","messageId":"V5_less_RFC_822_focus.b27@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 01/11] doc: interpret-trailers: stop fixating on RFC 822","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:25Z","receivedAt":"2026-08-09T20:07:35Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command handles the trailer metadata format. But the command\nisn’t introduced as such; it is instead introduced by stating that\nthese trailer lines look similar to RFC 822 email headers.\n\nThis is overwrought; most people do not deal directly with email\nheaders, and certainly not email RFCs.\n\nTrailers are just key–value pairs that, like email headers, use colon\nas the separator. The format in its simplest form is easy to describe\ndirectly without comparing it to anything else; we will do that in the\nupcoming commit “explain the format after the intro”.\n\nFor now, let’s:\n\n• remove the first mention of email headers;\n• keep the second, innocuous comparison with email line folding in the\n middle; and\n• remove the now-unneeded disclaimer that trailers do not share many of\n the features of RFC 822 email headers—there is no invitation to\n speculate that trailers would follow any other email format rules\n since we do not compare them directly any more.\n\n***\n\nTalking about trailers as an RFC 822/2822-like format seems to go back\nto the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated\nthis command and in turn the first trailer support in git(1) beyond\nadding s-o-b lines.\n\n† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: s/trailers metadata/trailer metadata/ (knock-on effect from\n change in the *next* commit)\n \n ---\n \n v2:\n • Use `***` as a thematic break instead of `❦`\n • Change to “metadata” instead of “key–value pairs” since this series\n version adds a paragraph after this one where we dig into this\n term. And “metadata” describes the purpose of this format.\n\n Documentation/git-interpret-trailers.adoc | 9 +++------\n 1 file changed, 3 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 77b4f63b05c..1878848ad2a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines that look similar to RFC 822 e-mail\n-headers, at the end of the otherwise free-form part of a commit\n-message. For example, in the following commit message\n+Add or parse _trailer_ lines at the end of the otherwise\n+free-form part of a commit message. For example, in the following commit\n+message\n \n ------------------------------------------------\n subject\n@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n-Note that trailers do not follow (nor are they intended to follow) many of the\n-rules for RFC 822 headers. For example they do not follow the encoding rule.\n-\n OPTIONS\n -------\n `--in-place`::\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550136","messageId":"V5_metadata_not_lines.b28@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 02/11] doc: interpret-trailers: replace “lines” with “metadata”","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:26Z","receivedAt":"2026-08-09T20:07:55Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe removed the initial comparison to email headers in the previous\ncommit. Now the introduction paragraph just says “trailer lines”, and\nthe only hint that this is metadata/structured information is the\n“otherwise free-form” phrase.\n\nLet’s replace “lines” with “metadata” since that is their purpose.\nThis also makes the introduction more consistent with how I chose\nto define trailers in the glossary:[1] “Key-value metadata”. (We will\nintroduce “key–value” in the upcoming commit “explain the format after\nthe intro”.)\n\n† 1: 68e3c69e (Documentation/glossary: describe \"trailer\", 2024-11-17)\n\nLet’s not emphasize “trailer” here since we are going to define the term\nin the upcoming commit “explain the format after the intro”.\n\nLet’s call it “trailer metadata” rather than “trailers metadata”.\nAt first it seemed better to use the latter:\n\n1. We’re introducing the jargon, and the format is often discussed as\n plural “trailers”, with its constituent parts being singular\n “trailer”\n2. What this replaces uses “trailer”, but it rescues the plural mood\n with “lines”\n3. This is very soon going to go into the constituent parts, including\n each trailer, so we’re contrasting the concept name (trailers) with\n its parts\n\nBut:\n\n1. The former reads better (most important)\n2. “Trailer *metadata*” suggests plurality, similar to “trailer *lines*”\n\nHelped-by: Matt Hunter \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • s/trailers metadata/trailer metadata/ since it reads better (and\n see commit message for details)\n \n 🔗 https://lore.kernel.org/git/DJ5W2I8UYXAA.3O4JQUHFMKP5X@lfurio.us/\n • Msg: Add a paragraph to explain why we remove the emphasis from\n “trailer”. In the previous version we replaced “trailer” with\n “trailers”, so we didn’t need to explain it then.\n \n ---\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 1878848ad2a..c8950d3babc 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]\n \n DESCRIPTION\n -----------\n-Add or parse _trailer_ lines at the end of the otherwise\n+Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message. For example, in the following commit\n message\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550137","messageId":"V5_metadata_Name_section.b29@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 03/11] doc: interpret-trailers: use “metadata” in Name as well","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:27Z","receivedAt":"2026-08-09T20:08:15Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe now since the previous commit introduce the format as “trailer\nmetadata”. We can replace “structured information” with “metadata”\nin the “Name” section to be consistent.\n\nWhile “structured information” does emphasize that the data is not\nloosely structured, we also say that this command adds to or parses\nthis format. I don’t think that we need to emphasize that it is\nstructured since clearly there is some structure there.\n\nBoth “metadata” and “structured information” can convey the same\ninformation. But “metadata” is shorter and easier to deploy since\nit’s just one word.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: s/trailers metadata/trailer metadata/ (knock-on effect from\n change in the prevoius commit)\n \n ---\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex c8950d3babc..5e776f0059a 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -3,7 +3,7 @@ git-interpret-trailers(1)\n \n NAME\n ----\n-git-interpret-trailers - Add or parse structured information in commit messages\n+git-interpret-trailers - Add or parse metadata in commit messages\n \n SYNOPSIS\n --------\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550138","messageId":"V5_cmt_msg_or_other_texts.b2a@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 04/11] doc: interpret-trailers: not just for commit messages","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:28Z","receivedAt":"2026-08-09T20:08:34Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis command doesn’t interface with commits directly. You can\ninterpret or modify any kind of text, even though commit messages\nare the most relevant.\n\nThe git(1) suite also isn’t restricted to only direct commit support\nsince git-tag(1) learned `--trailer` in 066cef77 (builtin/tag: add\n--trailer option, 2024-05-05)\n\nNow, we already introduce the command in the “Name” section as dealing\nwith commit messages as well. That is fine since that intro line needs\nto remain pretty short.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 5e776f0059a..ab3627c2cba 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty]\n DESCRIPTION\n -----------\n Add or parse trailer metadata at the end of the otherwise\n-free-form part of a commit message. For example, in the following commit\n-message\n+free-form part of a commit message, or any other kind of text.\n+For example, in the following commit message\n \n ------------------------------------------------\n subject\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550139","messageId":"V5_trailer_explain_format.b2b@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 05/11] doc: interpret-trailers: explain the format after the intro","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:29Z","receivedAt":"2026-08-09T20:08:54Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nYou need to read the entire “Description” section in order to understand\nthe full trailer format. But there are many nuances, so that’s fine.\nAs a starter though we have an introductory example.[1] That turns out\nto be crucial; the rest of this section talks about the mechanics of the\ncommand and only incidentally the format itself.\n\nNow, although the example might arguably be self-explanatory, we can\nadd a little preamble which defines the format in its simplest form as\nwell as define the most important terms.\n\nNote that we name the “blank line” rule since I want to use that term\nevery time it comes up. It gets very mildly obfuscated if you call it\na “blank line” in one place[2] and “empty (or whitespace-only) ...” in\nanother one.[3]\n\nWe will define the format of the *key* in the next commit.\n\n† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,\n 2023-06-15)\n† 2: `Documentation/git-interpret-trailers.adoc:86` in\n 5361983c (The 22nd batch, 2026-03-27)\n† 3: `Documentation/git-interpret-trailers.adoc:93` in\n 5361983c (The 22nd batch, 2026-03-27)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4: Msg: reflow paragraph\n \n v2: [new]\n • PS: Suggested here: https://lore.kernel.org/git/8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com/#t\n • (My tardiness on this topic has made these reminders necessary,\n if only for my own reference)\n\n Documentation/git-interpret-trailers.adoc | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex ab3627c2cba..109059f11ed 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -16,7 +16,12 @@ DESCRIPTION\n -----------\n Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n-For example, in the following commit message\n+\n+A _trailer_ in its simplest form is a key-value pair with a colon as a\n+separator. A _trailer block_ consists of one or more trailers. The\n+trailer block needs to be preceded by a blank line, where a _blank line_\n+is either an empty or a whitespace-only line. For example, in the\n+following commit message\n \n ------------------------------------------------\n subject\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550140","messageId":"V5_trailer_key_format.b2c@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 06/11] doc: interpret-trailers: explain key format","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:30Z","receivedAt":"2026-08-09T20:09:14Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nA trailer key must consist of ASCII alphanumeric characters and\nhyphens *only*. Let’s document it explicitly instead of relying on\nreaders being conservative and only basing their trailer keys on the\ndocumentation examples.[1]\n\nThe previous commit provided us with an appropriate paragraph to\ndescribe the key format.\n\n† 1: Technically they would then miss out on using digits in them since\n all of the example keys just use letters and hyphens\n\nReported-by: Brendan Jackman \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/\n • Remove the “paint by numbers” reference after review (unclear)\n • Add apropos footnote\n • Tweak the paragraph about how we now have a context to describe\n this format\n v1: [had a note about code spelunking (isalnum(3))]\n\n Documentation/git-interpret-trailers.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 109059f11ed..fb503cbe952 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -18,7 +18,8 @@ Add or parse trailer metadata at the end of the otherwise\n free-form part of a commit message, or any other kind of text.\n \n A _trailer_ in its simplest form is a key-value pair with a colon as a\n-separator. A _trailer block_ consists of one or more trailers. The\n+separator. The _key_ consists of ASCII alphanumeric characters and\n+hyphens (`-`). A _trailer block_ consists of one or more trailers. The\n trailer block needs to be preceded by a blank line, where a _blank line_\n is either an empty or a whitespace-only line. For example, in the\n following commit message\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550141","messageId":"V5_trailer_key_format_example.b2d@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 07/11] doc: interpret-trailers: add key format example","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:31Z","receivedAt":"2026-08-09T20:09:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nAll of the examples speak of the Happy Path where everything works\nas intended. But failure examples can also be instructive. Especially\nfor explaining again, by example, the key format (see previous commit).\n\nThis also allows us to demonstrate trailer block detection with a\nconcrete example.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4: Fix doubled word “to to”\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++\n 1 file changed, 23 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex fb503cbe952..a0f7ed6fdd9 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -405,6 +405,29 @@ mv \"\\$1.new\" \"\\$1\"\n $ chmod +x .git/hooks/commit-msg\n ------------\n \n+* Here we try to use three different trailer keys. But it fails because\n+ two of them are not recognized as trailer keys.\n++\n+----\n+$ cat msg.txt\n+subject\n+\n+Skapad-på: some-branch\n+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c\n+Reviewed-by: Alice \n+$ git interpret-trailers --only-trailers \n\nThere are three paragraphs that talk about how a new trailer is added.\nBut the first one is separated from the other two by two paragraphs\nabout how `key-alias` can make using `--trailer` more convenient. This\nshort how-to does not follow thematically from the previous paragraph,\nand can wait until we have fully described how a new trailer is\nadded. So let’s move the three paragraphs about the new-trailer topic\ntogether and move the how-to paragraphs after that.\n\n***\n\nLet’s now review the history of the document. Even if the document\nis not quite correct in its current state, just doing the apparently\nobvious edit without considering the history does not respect the\neffort that went into changing the document in the past.\n\nThese three paragraphs were originally next to each other, in the first\nversion of the doc.[1] But extra sentences about this how-to topic was\nadded to the first paragraph nine years later:[2]\n\n [...]\n `': '` (one colon followed by one space). For convenience, the\n can be a shortened string key (e.g., \"sign\") instead of the\n full string which should [...]\n\nAnd then it was split into it’s own paragraph a little later.[3]\n\nThis evolution shows, in my opinion, that this how-to never followed\nthematically from the existing topic. Which means that there is nothing\nthat was potentially lost to time that we need to restore or respect.\n\n† 1: dfd66ddf (Documentation: add documentation for 'git\n interpret-trailers', 2014-10-13)\n† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)\n† 3: 6ccbc667 (trailer doc: is a or , not both,\n 2023-09-07)\n\nSuggested-by: D. Ben Knoble \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Msg: Fix word-confusion: s/There are three trailers/There are\n three paragraphs.\n \n 🔗 https://lore.kernel.org/git/CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com/\n \n I knew that I was going to fix this when I started on\n version 4. But you would not believe how many times I\n went over the commit log without seeing that I had\n neglected to do this part.\n \n ---\n \n v3: [new]\n • Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/\n • Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]\n \n 🔗 1: https://lore.kernel.org/git/xmqqpl1zsv8s.fsf@gitster.g/\n\n Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex a0f7ed6fdd9..616f479a367 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -74,19 +74,6 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-For convenience, a __ can be configured to make using `--trailer`\n-shorter to type on the command line. This can be configured using the\n-`trailer..key` configuration variable. The __ must be a prefix\n-of the full __ string, although case sensitivity does not matter. For\n-example, if you have\n-\n-------------------------------------------------\n-trailer.sign.key \"Signed-off-by: \"\n-------------------------------------------------\n-\n-in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n-on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n-\n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n at the end of the input. A blank line will be added before the new\n@@ -101,6 +88,19 @@ The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with `---` (followed by a\n space or the end of the line).\n \n+For convenience, a __ can be configured to make using `--trailer`\n+shorter to type on the command line. This can be configured using the\n+`trailer..key` configuration variable. The __ must be a prefix\n+of the full __ string, although case sensitivity does not matter. For\n+example, if you have\n+\n+------------------------------------------------\n+trailer.sign.key \"Signed-off-by: \"\n+------------------------------------------------\n+\n+in your configuration, you only need to specify `--trailer=\"sign: foo\"`\n+on the command line instead of `--trailer=\"Signed-off-by: foo\"`.\n+\n When reading trailers, there can be no whitespace before or inside the\n __, but any number of regular space and tab characters are allowed\n between the __ and the separator. There can be whitespaces before,\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550143","messageId":"V5_trailer_block_term.b2f@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 09/11] doc: interpret-trailers: commit to “trailer block” term","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:33Z","receivedAt":"2026-08-09T20:10:13Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe chose to introduce the term “trailer block” into the documentation a\nfew commits ago.[1] It is used in the code though, so it is not a newly\ninvented term.\n\nThat term was useful to explain where the trailers are found (they\n*trail* the message). But it is also useful here, where we explain\nhow trailers are added to existing messages, how trailer blocks are\nfound (beyond the simple case in the introduction), and how the end\nof the message is found.\n\nAlso note that we simplify the “blank line” point. The text says:\n\n A blank line will be added before the new trailer if there isn't one\n already.\n\nBut this isn’t quite coherent. The previous sentence says “If there is\nno existing trailer”, so we are in one of these modes:\n\n1. discussing trailer blocks in general; or\n2. discussing creating a new trailer block in particular.\n\nIf (1), then we shouldn’t add a blank line before the new trailer if\nthere exists a trailer block already. And if (2), then the “if there\nisn’t one already” is redundant.[2] So just talking about the higher-\nlevel “trailer block” simplifies the text, since we don’t have to worry\nabout the different contexts that *trailers* can find themselves in.\n\n† 1: in commit “explain the format after the intro”\n† 2: Note that non-trailer lines don’t matter here; if you have a\n trailer block consisting of `(cherry picked from commit )`,\n then you still shouldn’t insert a blank line before the new trailer\n since that would create a new trailer block\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Tweak “blank line” reminder (“Recall that”) by dropping\n “specifically” since it is redundant based on [1]. Well, I\n thought I understood the feedback here but reading it again\n today I was confused. @Junio, did I understand it correctly?\n \n My thought process: This “recall that” is similar to other\n “recall” phrases added in the series. They add some redundancy,\n similar in spirit to 74522b6b (Documentation/git-update-ref.txt:\n discuss symbolic refs, 2024-10-21) :\n \n | Add a paragraph which just emphasizes that the command without\n | any options does not support refs in the final arguments. This\n | is clear already from the names `` and `` but\n | the right balance of redundancy makes documentation robust\n | against stray interpretation.\n • Msg: Editing the above I noticed that the previous (before this\n change “blank line” explanation isn’t (quite) coherent. I want to\n explain every meaningful point of change in the commit message, so\n I dedicate some “also” paragraphs to that change.\n • For [1] again: s/Concretely, that/A trailer block/ since it flows\n better\n • For [1] again: Fix mangled “The trailer block is by definition”\n sentence and make sure to use “commit message”. We use “commit\n message” throughout the doc, not just “message”. But just use\n “message” in the next sentence since it is clear that we are\n still talking about *commit* message.\n • Msg: Reflow existing paragraph\n \n 🔗 1: https://lore.kernel.org/git/xmqqcxxyt4op.fsf@gitster.g/#t\n \n ---\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------\n 1 file changed, 14 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex 616f479a367..a1adab20fef 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -74,19 +74,21 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-By default the new trailer will appear at the end of all the existing\n-trailers. If there is no existing trailer, the new trailer will appear\n-at the end of the input. A blank line will be added before the new\n-trailer if there isn't one already.\n-\n-Existing trailers are extracted from the input by looking for\n-a group of one or more lines that (i) is all trailers, or (ii) contains at\n-least one Git-generated or user-configured trailer and consists of at\n+By default the new trailer will appear at the end of the trailer block.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line will be inserted before the\n+new trailer block in that case.\n+\n+Existing trailers are extracted from the input by looking for the\n+trailer block. A trailer block is a group of one or more lines that (i)\n+is all trailers, or (ii) contains at least one Git-generated or\n+user-configured trailer and consists of at\n least 25% trailers.\n-The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the input or be the last\n-non-whitespace lines before a line that starts with `---` (followed by a\n-space or the end of the line).\n+The trailer block is by definition at the end of the commit message.\n+The message in turn is either (i) at the end of the input, or (ii) the\n+last non-whitespace lines before a line that starts with `---` (followed\n+by a space or the end of the line).\n \n For convenience, a __ can be configured to make using `--trailer`\n shorter to type on the command line. This can be configured using the\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550144","messageId":"V5_rewrite_new-trailers.b30@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:34Z","receivedAt":"2026-08-09T20:10:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTwo commits ago we moved new-trailers paragraph next to each other.\nBut there is something curious about two of them:\n\n By default the new trailer will appear at the end of the trailer\n block. [...]\n\nThen a source block and a paragraph later:\n\n By default, a `=` or `:` argument given\n using `--trailer` will be appended after the existing trailers only\n if [...]\n\nWhy are there two paragraphs that talk about how “By default” a trailer\nwill be appended?\n\nWe can make these paragraphs flow better, and with a more distinct\ncharacter each, by dividing the flow like this:\n\n1. Declare that we are about to talk about `--trailer` appending\n2. Explain the default behavior\n3. Explain how this affects the trailer block\n4. Then discuss what each trailer line will look like\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Simplify “This is how the new trailer” paragraph: drop “More\n concretely,” since it is misleading (this is not a “more\n concretely continuation of the preceding paragraph(s))[1]\n \n 🔗 1: https://lore.kernel.org/git/xmqqcxxyt4op.fsf@gitster.g/\n \n ---\n \n v3: [new]\n • Based on draft: https://lore.kernel.org/git/fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com/\n • See msg:\n \n Two commits ago we moved new-trailers paragraph next to\n each other.\n \n This commit here might fit better one step back. So that it\n becomes the commit right after. But I can deal with that commit\n movement if this change is accepted. For now I didn’t bother.\n\n Documentation/git-interpret-trailers.adoc | 22 ++++++++++++----------\n 1 file changed, 12 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex a1adab20fef..ac59ef51f80 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -60,10 +60,18 @@ are applied to each input and the way any existing trailer in\n the input is changed. They also make it possible to\n automatically add some trailers.\n \n-By default, a `=` or `:` argument given\n-using `--trailer` will be appended after the existing trailers only if\n-the last trailer has a different (__, __) pair (or if there\n-is no existing trailer). The __ and __ parts will be trimmed\n+Let's consider new trailers added with `--trailer`.\n+By default, the new trailer will appear at the end of the trailer block.\n+Also by default, this new trailer will only be added\n+if the last trailer is different to it.\n+A trailer block will be created with only that trailer if a trailer\n+block does not already exist. Recall that a trailer block needs to be\n+preceded by a blank line, so a blank line will be inserted before the\n+new trailer block in that case.\n+\n+This is how the new trailer is added: a `=` or\n+`:` argument given using `--trailer` will be appended after\n+the existing trailers. The __ and __ parts will be trimmed\n to remove starting and trailing whitespace, and the resulting trimmed\n __ and __ will appear in the output like this:\n \n@@ -74,12 +82,6 @@ key: value\n This means that the trimmed __ and __ will be separated by\n \"`:`{nbsp}\" (one colon followed by one space).\n \n-By default the new trailer will appear at the end of the trailer block.\n-A trailer block will be created with only that trailer if a trailer\n-block does not already exist. Recall that a trailer block needs to be\n-preceded by a blank line, so a blank line will be inserted before the\n-new trailer block in that case.\n-\n Existing trailers are extracted from the input by looking for the\n trailer block. A trailer block is a group of one or more lines that (i)\n is all trailers, or (ii) contains at least one Git-generated or\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550145","messageId":"V5_trailer_comment_lines.b31@msgid.xyz","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"[PATCH v5 11/11] doc: interpret-trailers: document comment line treatment","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-09T20:06:35Z","receivedAt":"2026-08-09T20:10:53Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nComment lines have always been ignored but this is not documented.\n\nThe primary motivation here is to be reasonably complete in the\ndocumentation of how trailers are parsed; this is after all the only\ndocumentation page that documents this format. However, and going beyond\nthat point, we could imagine that someone would want to use this format\noutside a commit (or tag) message context, like say in Git notes.\n\nOn the other hand, it seems far-fetched that someone would be caught\noff guard by this considering that comment characters/strings are not\nlikely to be alphanumeric,[1] which would mean that these comment lines\nwould be treated as non-trailer lines if they were *not* detected and\nremoved as comment lines.\n\n† 1: A notable exception is that Jujutsu VCS uses `JJ:` as\n the comment string\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v5:\n • Msg: add missing word: s/to/to be/[1]\n 🔗 1: https://lore.kernel.org/git/CALnO6CB_0ucqnAowrNcPmsXmxxDfJQZPVGkbsHVuya7NLR4dsg@mail.gmail.com/\n \n ---\n \n v4:\n • Msg: rewrite motivation for documenting this. The motivation is\n not super solid, but it reflects my own ambiguity on the matter,\n so to speak; I think we ought to be very thorough about\n documenting the format, while making sure to not use the main text\n to exhaustively lay it all out. The information should be\n somewhere in this doc. But not in your face.\n • Msg: Add “(or tag) message”. See patch “not just for commit\n messages” where trailer support for tag messages are mentioned.\n \n ---\n \n v3:\n • Msg: finally fix area\n • Demote this point to its own “other rules” section, out of the main\n running text. It is not important enough for the main text.\n • Since writing this I have realized that we can go into that long\n \n # ----- >8 ----\n \n Commit message separator scissor line, maybe other things. But I stop\n short here. These things are even less likely to become a problem for\n anyone. And maybe we’ll add them later?\n \n v2: [new]\n\n Documentation/git-interpret-trailers.adoc | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc\nindex ac59ef51f80..b4988d39eab 100644\n--- a/Documentation/git-interpret-trailers.adoc\n+++ b/Documentation/git-interpret-trailers.adoc\n@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and\n newlines in it.\n ------------------------------------------------\n \n+OTHER RULES\n+-----------\n+\n+What was covered in the previous section are the rules that are relevant\n+for regular use. The following points are included for completeness.\n+\n+This command ignores comment lines (see `core.commentString` in\n+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`\n+and `commit-msg` hooks.\n+\n OPTIONS\n -------\n `--in-place`::\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"550167","messageId":"0687D60D-DF6B-4547-868C-FCFC5B27ECAF@gmail.com","threadId":"63233","inReplyTo":"V5_CV_doc_int-tr_key_format.b26@msgid.xyz","subject":"Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-08-10T11:16:56Z","receivedAt":"2026-08-10T11:17:12Z","isPatch":true,"body":"\n> Le 9 août 2026 à 16:07, kristofferhaugsbakk@fastmail.com a écrit :\n> \n> From: Kristoffer Haugsbakk \n> \n> Topic name (applied): kh/doc-trailers\n> \n> Topic summary: Explain the format of trailer keys (alphanum and\n> hyphens). This is important to keep in mind so that metadata is not\n> lost to simple syntax errors. Also replace some terms and define the\n> important ones upfront.\n> \n> Here one change lead to another in order to make sure that everything\n> stayed coherent. So here’s a linear overview of the changes (as of v4):\n> \n> • Patches 1–3: remove RFC 822 mentions, “metadata” term\n> • Patch 4: This command is not just for commit messages\n> • Patches 5–7: Explain the format in the simplest case, explain\n> the “key” format, and add a new example\n> • Patch 8: join some existing paragraphs that are about the same theme\n> since that makes the text flow better\n> • Patch 9: Also use the “trailer block” term introduced to the doc in\n> patch 5 later in the doc\n> • Patch 10: Rewrite new-trailer paragraphs (relates to patch 8)\n> • Patch 11: document line comment behavior\n> \n> Thanks to everyone who has been reviewing these so far. I understand that\n> these eleven changes are very incremental and piecemeal (see “very\n> cross-referenced commit messages”). And the commit messages can be quite\n> long, just to explain (again) very small changes. See for example patch\n> “replace “lines” with “metadata”” in this version, where I explain why to\n> write “trailer metadata” instead of “trailers metadata”. But right now I\n> feel like prose sometimes needs all this ceremony. With code you get\n> restraints like coding style, then you have all the years of looser rules\n> about when to use certain data structures, when to make helper methods,\n> etc. But with prose it seems that you bring much more of your individuality\n> to it. That means more choices, and many of them are not obvious to the\n> reader of the document, which means that you need to explain it in the\n> commit message. Then you also have to consider the writing history of the\n> document, and this one is twelve years old at this point; see the history\n> review in commit message “join new-trailers again”, after the thematic\n> break (***).\n> \n> § Changes in v5\n> \n> Patch “document comment line treatment”: commit message: add missing word:\n> s/to/to be/.\n> \n> § Apologies for very cross-referenced commit messages\n> \n> (see v3)\n> \n> § Cc\n> \n> (see v2)\n> \n> https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/\n> \n> I have also added a new email since the email jackmanb@google.com bounces\n> for me. There is a Brendan Jackman who has posted messages under a Gmail\n> address. Hopefully it’s the same person.\n> \n> § In-reply-to: v1\n> \n> The recommendation to reply to the first version/cover letter is from topic\n> ps/doc-recommend-b4, which is in `next` right now.\n> \n> § Link to v4\n> \n> https://lore.kernel.org/git/V4_CV_doc_int-tr_key_format.ae2@msgid.xyz/\n> \n> [01/11] doc: interpret-trailers: stop fixating on RFC 822\n> [02/11] doc: interpret-trailers: replace “lines” with “metadata”\n> [03/11] doc: interpret-trailers: use “metadata” in Name as well\n> [04/11] doc: interpret-trailers: not just for commit messages\n> [05/11] doc: interpret-trailers: explain the format after the intro\n> [06/11] doc: interpret-trailers: explain key format\n> [07/11] doc: interpret-trailers: add key format example\n> [08/11] doc: interpret-trailers: join new-trailers again\n> [09/11] doc: interpret-trailers: commit to “trailer block” term\n> [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs\n> [11/11] doc: interpret-trailers: document comment line treatment\n> \n> Documentation/git-interpret-trailers.adoc | 88 ++++++++++++++++-------\n> 1 file changed, 64 insertions(+), 24 deletions(-)\n> \n> Interdiff against v4:\n> Range-diff against v4:\n> 1: 2419b1a6863 = 1: 2419b1a6863 doc: interpret-trailers: stop fixating on RFC 822\n> 2: 859ab42ac41 = 2: 859ab42ac41 doc: interpret-trailers: replace “lines” with “metadata”\n> 3: ab5b4af970e = 3: ab5b4af970e doc: interpret-trailers: use “metadata” in Name as well\n> 4: b79ddf3b13e = 4: b79ddf3b13e doc: interpret-trailers: not just for commit messages\n> 5: e7101eb1fcb = 5: e7101eb1fcb doc: interpret-trailers: explain the format after the intro\n> 6: 557b5b5564a = 6: 557b5b5564a doc: interpret-trailers: explain key format\n> 7: eee81fc99fa = 7: eee81fc99fa doc: interpret-trailers: add key format example\n> 8: cd3e47459c7 = 8: cd3e47459c7 doc: interpret-trailers: join new-trailers again\n> 9: c50b6d25170 = 9: c50b6d25170 doc: interpret-trailers: commit to “trailer block” term\n> 10: c11a116605e = 10: c11a116605e doc: interpret-trailers: rewrite new-trailers paragraphs\n> 11: 7d20cb7528f ! 11: cabbb05a1c4 doc: interpret-trailers: document comment line treatment\n> @@ Commit message\n> \n> Comment lines have always been ignored but this is not documented.\n> \n> - The primary motivation here is to reasonably complete in the\n> + The primary motivation here is to be reasonably complete in the\n> documentation of how trailers are parsed; this is after all the only\n> documentation page that documents this format. However, and going beyond\n> that point, we could imagine that someone would want to use this format\n> \n> base-commit: 5361983c075154725be47b65cca9a2421789e410\n> --\n> 2.54.0.22.g9e26862b904\n\nI’m trivially satisfied with the range-diff (note again I’ve reviewed primarily the end result, not the per-commit history).\n\nBest,\nBen"},{"id":"550189","messageId":"707ccba1-22bc-4673-9536-7110a96ae05b@app.fastmail.com","threadId":"63233","inReplyTo":"0687D60D-DF6B-4547-868C-FCFC5B27ECAF@gmail.com","subject":"Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-10T14:12:59Z","receivedAt":"2026-08-10T14:13:26Z","isPatch":true,"body":"On Mon, Aug 10, 2026, at 13:16, Ben Knoble wrote:\n>> Le 9 août 2026 à 16:07, kristofferhaugsbakk@fastmail.com a écrit :\n>>[snip]\n> I’m trivially satisfied with the range-diff (note again I’ve reviewed \n> primarily the end result, not the per-commit history).\n\nThank you for the review and for sticking\nwith this series.\n\nKris\n\nsent from mobile\n"},{"id":"550225","messageId":"xmqqpkzp60be.fsf@gitster.g","threadId":"63233","inReplyTo":"0687D60D-DF6B-4547-868C-FCFC5B27ECAF@gmail.com","subject":"Re: [PATCH v5 00/11] doc: interpret-trailers: explain key format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-08-10T23:08:21Z","receivedAt":"2026-08-10T23:08:24Z","isPatch":true,"body":"Ben Knoble writes:\n\n>> § Link to v4\n>> \n>> https://lore.kernel.org/git/V4_CV_doc_int-tr_key_format.ae2@msgid.xyz/\n>> \n>> [01/11] doc: interpret-trailers: stop fixating on RFC 822\n>> [02/11] doc: interpret-trailers: replace “lines” with “metadata”\n>> [03/11] doc: interpret-trailers: use “metadata” in Name as well\n>> [04/11] doc: interpret-trailers: not just for commit messages\n>> [05/11] doc: interpret-trailers: explain the format after the intro\n>> [06/11] doc: interpret-trailers: explain key format\n>> [07/11] doc: interpret-trailers: add key format example\n>> [08/11] doc: interpret-trailers: join new-trailers again\n>> [09/11] doc: interpret-trailers: commit to “trailer block” term\n>> [10/11] doc: interpret-trailers: rewrite new-trailers paragraphs\n>> [11/11] doc: interpret-trailers: document comment line treatment\n\n[...]\n\n>> @@ Commit message\n>> \n>> Comment lines have always been ignored but this is not documented.\n>> \n>> - The primary motivation here is to reasonably complete in the\n>> + The primary motivation here is to be reasonably complete in the\n>> documentation of how trailers are parsed; this is after all the only\n>> documentation page that documents this format. However, and going beyond\n>> that point, we could imagine that someone would want to use this format\n>> \n>> base-commit: 5361983c075154725be47b65cca9a2421789e410\n>> --\n>> 2.54.0.22.g9e26862b904\n>\n> I’m trivially satisfied with the range-diff (note again I’ve reviewed primarily the end result, not the per-commit history).\n\nHeh, that is like saying it is better with \"be\" than without ;-).\n\nI think the topic was already in pretty good shape by 'v4'. Shall\nwe declare victory and mark the topic for 'next'?\n\nThanks.\n"},{"id":"550550","messageId":"a4956b42-62b0-4649-ba5d-79e7647df985@app.fastmail.com","threadId":"63233","inReplyTo":"21339fd9-9fcf-46ea-8896-9fde56cd1f29@app.fastmail.com","subject":"Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-13T17:43:41Z","receivedAt":"2026-08-13T17:44:08Z","isPatch":true,"body":"On Thu, Jul 30, 2026, at 11:20, Kristoffer Haugsbakk wrote:\n> On Fri, Jul 24, 2026, at 01:48, Junio C Hamano wrote:\n>> \"Kristoffer Haugsbakk\" writes:\n>>\n>> I was reviewing the draft of the What's Cooking report and noticed\n>> that this topic is among a handful of stalled efforts going nowhere.\n>>\n>>>> If you want to stress that a line with only whitespaces on it does\n>>>> not count as a blank line for the purpose of this paragraph, you can\n>>>> consistently say \"an empty line\" withotu saying \"a blank line\", and\n>>>> you do not need to have \"(specifically an empty lline)\" there.\n>>>\n>>> Okay, I’ll make it shorter.\n>>>\n>>> It felt too long for a simple concept indeed.\n>>> ...\n>>\n>> And it has been more than a month since we discussed this topic the\n>> last time. Will we see an update anytime soon? If not, let me\n>> mark the topic to be discarded in my draft of the whats-cooking\n>> report.\n>\n> I’ve posted the next version now.\n\nAnd I’m sorry for not simply sending a message sometime in July that\nthis topic was stalled. I was _not_ away from the computer for over a\nmonth, and I could have easily sent a quick message about the status.\n"}]}