[PATCH v5 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs
From: <hidden>
Date: 2026-08-09 20:10:33
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
From: Kristoffer Haugsbakk <redacted>
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 <redacted>
---
Notes (series):
v4:
• Simplify “This is how the new trailer” paragraph: drop “More
concretely,” since it is misleading (this is not a “more
concretely continuation of the preceding paragraph(s))[1]
🔗 1: https://lore.kernel.org/git/xmqqcxxyt4op.fsf@gitster.g/ (local)
---
v3: [new]
• Based on draft: https://lore.kernel.org/git/fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com/ (local)
• See msg:
Two commits ago we moved new-trailers paragraph next to
each other.
This commit here might fit better one step back. So that it
becomes the commit right after. But I can deal with that commit
movement if this change is accepted. For now I didn’t bother.
Documentation/git-interpret-trailers.adoc | 22 ++++++++++++----------
1 file changed, 12 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index a1adab20fef..ac59ef51f80 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
--
2.54.0.22.g9e26862b904