Re: [PATCH 2/2] doc: interpret-trailers: explain key format
- From
- Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
- Date
- Mar 31, 2026, 16:03 UTC
- 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:
Show 17 quoted lines
>> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> 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:
<text>
<key>: <value>
Where <key> 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 <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------------------------------------------
***
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