@leroysheep / LeeRoySheep / commits / 55afc1f9aa

doc: interpret-trailers: rewrite new-trailers paragraphs

Two commits ago we moved new-trailers paragraph next to each other. But there is something curious about two of them: By default the new trailer will appear at the end of the trailer block. [...] Then a source block and a paragraph later: By default, a `<key>=<value>` or `<key>:<value>` argument given using `--trailer` will be appended after the existing trailers only if [...] Why are there two paragraphs that talk about how “By default” a trailer will be appended? We can make these paragraphs flow better, and with a more distinct character each, by dividing the flow like this: 1. Declare that we are about to talk about `--trailer` appending 2. Explain the default behavior 3. Explain how this affects the trailer block 4. Then discuss what each trailer line will look like Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Kristoffer Haugsbakk committed Jul 30, 2026 at 11:18 UTC 55afc1f9aa7a2992d4ea684a0091cdb1cf5efdae

1 file changed +12 -10

Documentation/git-interpret-trailers.adoc

+12 -10

index a1adab20fe..ac59ef51f8 100644 --- a/Documentation/git-interpret-trailers.adoc +++ b/Documentation/git-interpret-trailers.adoc @@ -60,10 +60,18 @@ 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. -By default, a `<key>=<value>` or `<key>:<value>` argument given -using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (_<key>_, _<value>_) pair (or if there -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed +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 will be inserted before the +new trailer block in that case. + +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: @@ -74,12 +82,6 @@ key: value This means that the trimmed _<key>_ and _<value>_ will be separated by "`:`{nbsp}" (one colon followed by one space). -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 will be inserted before the -new trailer block in that case. - Existing trailers are extracted from the input by looking for the trailer block. A trailer block is a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or