From: Kristoffer Haugsbakk Date: Tue, 31 Mar 2026 16:03:46 GMT Subject: Re: [PATCH 2/2] doc: interpret-trailers: explain key format Message-ID: <660b739f-a738-4359-92bd-cb24f5bcd624@app.fastmail.com> In-Reply-To: <8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com> On Tue, Mar 31, 2026, at 14:35, Ben Knoble wrote: >> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk a écrit : >>>[snip] >> >> Key & value. >> >> Something like: >> >> Just like *trailer* we emphasize these two first standalone word >> mentions (key and value). >> >> They are the only emphasized words in the diff. Although I *have* relied >> too much on the diff context before. > > Perhaps “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)? I think I’ll steal that. Thanks! > I do find it interesting that the introduction is with an example > rather than a definition. The example is from Linus Arver in d57fa7fc (doc: trailer: add more examples in DESCRIPTION, 2023-06-15).[1] The version before that[2] indirectly showed a `token: value` example (“will appear in the output like”) after five paragraphs. † 1: One review comment: https://lore.kernel.org/git/xmqqmt2emwlj.fsf@gitster.g/ † 2: `git show d57fa7fc73202af226b6c0^1:Documentation/git-interpret-trailers.txt` > This suits “learning order” (concrete->abstract), but not necessarily > “reference order” (where I just want to get to the definition). Hm. > > I’m not sure I have any concrete suggestions, though. I think the only practical starting point for this format is the simplest case first, namely: 1. One line per trailer (c.f. the value takes up multiple lines) 2. Non-empty values (see `--trim-empty`) 3. Default separator 4. No non-trailer lines 5. No configuration Currently that starts off with two examples. But let’s try the other way around: *** A _trailer_ in its simplest form is a key-value pair with a colon as a separator. The _key_ consists of ASCII alphanumeric characters and hyphens (`-`). A _trailer block_ consists of one or more such trailers. The trailer block needs to be preceded by a blank line.[**1**] In other words: : Where consists of ASCII alphanumeric characters and hyphens. For example: [we’re back to the original example] ------------------------------------------------ subject Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Alice Signed-off-by: Bob ------------------------------------------------ *** Also optionally interject some words about commit messages and whatnot (or even tag messages for that matter, now). I was originally feeling skeptical of changing to something like reference-first. But I like this now that I have gone through the exercise of trying it out. So thanks for mentioning it. ;) [**1**]: git-commit(1) stripspace behavior etc. doesn’t make this obvious but you can have just a blank line and then a trailer block. You don’t need any text before the blank line. `LF` indicates the blank line: LF Signed-off-by: Me