From: Ben Knoble Date: Tue, 26 May 2026 21:34:56 GMT Subject: Re: [PATCH v2 0/9] doc: interpret-trailers: explain key format Message-ID: <4DD440D4-145A-4A9E-ACBA-8E6ACFA231D1@gmail.com> In-Reply-To: > Le 24 mai 2026 à 08:41, Kristoffer Haugsbakk a écrit : > > On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote: >> Overall looks good to me. Repeating a few points throughout the doc >> might create headaches if format restrictions are changed, but I think >> they are essential points worth repeating for now. > > Thanks for taking a look again. :) Thank you for working on it :) >>> [snip] >>> @@ -81,19 +87,25 @@ trailer.sign.key "Signed-off-by: " >>> in your configuration, you only need to specify `--trailer="sign: foo"` >>> on the command line instead of `--trailer="Signed-off-by: foo"`. >>> >>> -By default the new trailer will appear at the end of all the existing >>> -trailers. If there is no existing trailer, the new trailer will appear >>> -at the end of the input. A blank line will be added before the new >>> -trailer if there isn't one already. >>> +By default the new trailer will appear at the end of the trailer block. >>> +A trailer block will be created with only that trailer if a trailer >>> +block does not already exist. Recall that a trailer block needs to be >>> +preceded by a blank line, so a blank line (specifically an empty line) >>> +will be inserted before the new trailer block in that case. >> >> [not strictly related to this patch, but while we're here…] >> >> Even in context, I find the original (and new) paragraph somewhat >> jarring. In "the new trailer," there's no antecedent for "the >> trailer", so which new trailer are we talking about? The previous >> paragraph is about "es" for --trailer=": value". >> >> We _could_ move this paragraph up one, so that it follows the >> paragraph on trailers being appended when given with --trailer. >> >> Either way, adjusting "the new trailer" to "a new trailer" might feel >> better to me. Other suggestions welcome. > > The paragraph about new trailers originally came right after the > separated-by sentence:[1] > > By default, a '=' or ':' [...] > > ------------------------------------------------ > token: value > ------------------------------------------------ > > This means that the trimmed and will be separated by > `': '` (one colon followed by one space). > > By default the new trailer will appear [...] > > † 1: dfd66ddf (Documentation: add documentation for 'git > interpret-trailers', 2014-10-13) > > Nine years later in [2], a “For convenience, ” was added to that *existing paragraph: > > [...] > `': '` (one colon followed by one space). For convenience, the can be a > shortened string key (e.g., "sign") instead of the full string which should > appear before the separator on the output (e.g., "Signed-off-by"). This can be > configured using the 'trailer..key' configuration variable. > > By default the new trailer will appear at the end [...] > > † 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15) > > A little later in [3], that part was split into its own paragraph—and > expanded into two more blocks (source block and paragraph): > > [...] and will be separated by `': '` (one colon followed > by one space). > > For convenience, a can be configured to [...] > > ------------------------------------------------ > key: value > ------------------------------------------------ > > in your configuration, [...] > > By default the new trailer will appear at the end [...] > > † 3: 6ccbc667 (trailer doc: is a or , not both, > 2023-09-07) > >> We _could_ move this paragraph up one, so that it follows the >> paragraph on trailers being appended when given with --trailer. > > But going back to commit [1], there are two paragraphs that talk about > how “By default” the new trailer will be appended to the end: > > By default, a '=' or ':' argument given > using `--trailer` will be appended after the existing trailers only if > the last trailer has a different (, ) pair (or if there > is no existing trailer). The and parts will be trimmed > to remove starting and trailing whitespace, and the resulting trimmed > and will appear in the message like this: > > ------------------------------------------------ > token: value > ------------------------------------------------ > > This means that the trimmed and will be separated by > `': '` (one colon followed by one space). > > By default the new trailer will appear at the end of all the existing > trailers. If there is no existing trailer, the new trailer will appear > after the commit message part of the ouput, and, if there is no line > with only spaces at the end of the commit message part, one blank line > will be added before the new trailer. > > These two seem to overlap? They both talk about appending. Why does one > talk about how specifically / and will be treated > when appended, then a later paragraph *also* says that it will be > appended? > > Here is a draft of this part of the doc. I have tried to consolidate > these two “By default” paragrahs and be more explicit about what “the > trailer” is. I have included one unchanged paragraph before and after > for context. I’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. Whether you roll that into this patch series or wait until the dust settles is up to you. > *** > > Some configuration variables control the way the `--trailer` arguments > are applied to each input and the way any existing trailer in > the input is changed. They also make it possible to > automatically add some trailers. > > Let's consider new trailers added with `--trailer`. > By default, the new trailer will appear at the end of the trailer block. > Also by default, this new trailer will only be added > if the last trailer is different to it. > A trailer block will be created with only that trailer if a trailer > block does not already exist. Recall that a trailer block needs to be > preceded by a blank line, so a blank line (specifically an empty line) > will be inserted before the new trailer block in that case. > > More concretely, this is how the new trailer is added: a `=` > or `:` argument given using `--trailer` will be appended > after the existing trailers. The __ and __ parts will be > trimmed to remove starting and trailing whitespace, and the resulting > trimmed __ and __ will appear in the output like this: > > ------------------------------------------------ > key: value > ------------------------------------------------ > > This means that the trimmed __ and __ will be separated by > "`:`{nbsp}" (one colon followed by one space). > > *** > >> [snip] >>> -a group of one or more lines that (i) is all trailers, or (ii) contains at >>> -least one Git-generated or user-configured trailer and consists of at >>> +Existing trailers are extracted from the input by looking for the >>> +trailer block. Concretely, that is a group of one or more lines that (i) >>> +is all trailers, or (ii) contains at least one Git-generated or >>> +user-configured trailer and consists of at >>> [snip]