From: kristofferhaugsbakk@fastmail.com Date: Mon, 30 Mar 2026 21:11:32 GMT Subject: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822 Message-ID: In-Reply-To: From: Kristoffer Haugsbakk This command handles the *trailers* key–value pair format. But the command isn’t introduced as such; it is instead introduced by stating that these trailer lines look similar to RFC 822 email headers. This is overwrought: • most people do not deal directly with email headers or think about email RFCs; and • simply calling them “key-value pairs” should be more than suggestive enough considering the context here. Se let’s call the format just that, show the example, and then briefly explain the format of the keys (coming up); this change facilitates the next commit where we will explain what characters are permitted in the key. Concretely, let’s replace the introduction with “key-value pairs” and remove the last mention of RFC 822, but keep the innocuous comparison with email line folding in the middle. We do not need the final disclaimer now that the *only* mention of email headers is that Git trailers have something similar to email line folding; there is no invitation to speculate that trailers would follow any other email format rules since we do not compare them directly any more. ❦ Talking about trailers as an RFC 822/2822-like format seems to go back to the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated this command and in turn the first trailer support in git(1) beyond adding s-o-b lines. † 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/ Signed-off-by: Kristoffer Haugsbakk --- Notes (series): The (❦) is meant as a thematic break. There is too much of a thematic jump between these two paragraphs without a section or something else breaking them up. (one was not tempted to use `---` here) Documentation/git-interpret-trailers.adoc | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc index 77b4f63b05c..e7c1f821619 100644 --- a/Documentation/git-interpret-trailers.adoc +++ b/Documentation/git-interpret-trailers.adoc @@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty] DESCRIPTION ----------- -Add or parse _trailer_ lines that look similar to RFC 822 e-mail -headers, at the end of the otherwise free-form part of a commit -message. For example, in the following commit message +Add or parse _trailer_ key-value pairs at the end of the otherwise +free-form part of a commit message. For example, in the following commit +message ------------------------------------------------ subject @@ -107,9 +107,6 @@ key: This is a very long value, with spaces and newlines in it. ------------------------------------------------ -Note that trailers do not follow (nor are they intended to follow) many of the -rules for RFC 822 headers. For example they do not follow the encoding rule. - OPTIONS ------- `--in-place`:: -- 2.53.0.32.gf6228eaf9cc