Le 24 mai 2026 à 08:41, Kristoffer Haugsbakk [off-list ref] a écrit :

On Mon, May 11, 2026, at 21:23, D. Ben Knoble wrote:

quoted

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 :)

quoted

quoted

[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 "<key-alias>es" for --trailer="<key>: 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 '<token>=<value>' or '<token>:<value>' [...]

   ------------------------------------------------
   token: value
   ------------------------------------------------

   This means that the trimmed <token> and <value> 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, <token>” was added to that *existing paragraph:

   [...]
   `': '` (one colon followed by one space). For convenience, the <token> 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.<token>.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):

   [...] <key> and <value> will be separated by `': '` (one colon followed
   by one space).

   For convenience, a <keyAlias> can be configured to [...]

   ------------------------------------------------
   key: value
   ------------------------------------------------

   in your configuration, [...]

   By default the new trailer will appear at the end [...]

† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
    2023-09-07)

quoted

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 '<token>=<value>' or '<token>:<value>' argument given
   using `--trailer` will be appended after the existing trailers only if
   the last trailer has a different (<token>, <value>) pair (or if there
   is no existing trailer). The <token> and <value> parts will be trimmed
   to remove starting and trailing whitespace, and the resulting trimmed
   <token> and <value> will appear in the message like this:

   ------------------------------------------------
   token: value
   ------------------------------------------------

   This means that the trimmed <token> and <value> 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 <token>/<key> and <value> 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 `<key>=<value>`
or `<key>:<value>` argument given using `--trailer` will be appended
after the existing trailers. The _<key>_ and _<value>_ parts will be
trimmed to remove starting and trailing whitespace, and the resulting
trimmed _<key>_ and _<value>_ will appear in the output like this:

------------------------------------------------
key: value
------------------------------------------------

This means that the trimmed _<key>_ and _<value>_ will be separated by
"`:`{nbsp}" (one colon followed by one space).

***

quoted

[snip]

quoted

-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]