From: kristofferhaugsbakk@fastmail.com
To: git@vger.kernel.org
Cc: Kristoffer Haugsbakk <code@khaugsbakk.name>,
christian.couder@gmail.com, jackmanb@google.com,
Linus Arver <linus@ucla.edu>,
"D . Ben Knoble" <ben.knoble@gmail.com>
Subject: [PATCH v3 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs
Date: Wed, 10 Jun 2026 23:21:28 +0200 [thread overview]
Message-ID: <<>> (raw)
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 state the same thing (“More concretely”) in concrete terms with
placeholders
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v3: [new]
• Based on draft: https://lore.kernel.org/git/fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com/
• 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 | 26 ++++++++++++-----------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 9f4c84abfd9..fb9b1e94dd7 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -60,12 +60,20 @@ 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
-to remove starting and trailing whitespace, and the resulting trimmed
-_<key>_ and _<value>_ will appear in the output like this:
+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
@@ -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 (specifically an empty 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. Concretely, that 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
next prev parent reply other threads:[~2026-06-10 21:24 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-04-01 13:27 git-interpret-trailers and period characters in the key Brendan Jackman
2025-04-03 11:07 ` Christian Couder
2025-04-07 20:37 ` Junio C Hamano
2026-03-30 21:11 ` [PATCH 0/2] doc: interpret-trailers: explain key format kristofferhaugsbakk
2026-03-30 21:11 ` [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822 kristofferhaugsbakk
2026-03-30 22:27 ` Junio C Hamano
2026-03-30 22:56 ` Kristoffer Haugsbakk
2026-03-30 23:24 ` Junio C Hamano
2026-03-30 21:11 ` [PATCH 2/2] doc: interpret-trailers: explain key format kristofferhaugsbakk
2026-03-30 21:55 ` Junio C Hamano
2026-03-30 22:23 ` Kristoffer Haugsbakk
2026-03-31 12:35 ` Ben Knoble
2026-03-31 16:03 ` Kristoffer Haugsbakk
2026-04-13 10:20 ` [PATCH v2 0/9] " kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 1/9] doc: interpret-trailers: stop fixating on RFC 822 kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 2/9] doc: interpret-trailers: replace “lines” with “metadata” kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 3/9] doc: interpret-trailers: use “metadata” in Name as well kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 4/9] doc: interpret-trailers: not just for commit messages kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 5/9] doc: interpret-trailers: explain the format after the intro kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 6/9] doc: interpret-trailers: explain key format kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 7/9] doc: interpret-trailers: add key format example kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 8/9] doc: interpret-trailers: commit to “trailer block” term kristofferhaugsbakk
2026-04-13 10:21 ` [PATCH v2 9/9] doc: intepret-trailers: document comment line treatment kristofferhaugsbakk
2026-04-13 13:26 ` Kristoffer Haugsbakk
2026-04-13 15:48 ` Junio C Hamano
2026-05-08 15:03 ` Kristoffer Haugsbakk
2026-05-08 15:01 ` [PATCH v2 0/9] doc: interpret-trailers: explain key format Kristoffer Haugsbakk
2026-05-11 2:41 ` Junio C Hamano
2026-05-11 19:23 ` D. Ben Knoble
2026-05-24 12:41 ` Kristoffer Haugsbakk
2026-05-26 21:34 ` Ben Knoble
2026-05-26 21:42 ` Kristoffer Haugsbakk
2026-05-26 21:45 ` Kristoffer Haugsbakk
2026-06-10 21:21 ` [PATCH v3 00/11] " kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 01/11] doc: interpret-trailers: stop fixating on RFC 822 kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata” kristofferhaugsbakk
2026-06-11 3:10 ` Matt Hunter
2026-06-10 21:21 ` [PATCH v3 03/11] doc: interpret-trailers: use “metadata” in Name as well kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 04/11] doc: interpret-trailers: not just for commit messages kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 05/11] doc: interpret-trailers: explain the format after the intro kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 06/11] doc: interpret-trailers: explain key format kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 07/11] doc: interpret-trailers: add key format example kristofferhaugsbakk
2026-06-10 21:21 ` [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again kristofferhaugsbakk
2026-06-10 22:00 ` D. Ben Knoble
2026-06-10 22:13 ` Kristoffer Haugsbakk
2026-06-10 21:21 ` [PATCH v3 09/11] doc: interpret-trailers: commit to “trailer block” term kristofferhaugsbakk
2026-06-10 21:21 ` kristofferhaugsbakk [this message]
2026-06-10 21:21 ` [PATCH v3 11/11] doc: interpret-trailers: document comment line treatment kristofferhaugsbakk
2026-06-10 22:24 ` [PATCH v3 00/11] doc: interpret-trailers: explain key format Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='<>' \
--to=kristofferhaugsbakk@fastmail.com \
--cc=ben.knoble@gmail.com \
--cc=christian.couder@gmail.com \
--cc=code@khaugsbakk.name \
--cc=git@vger.kernel.org \
--cc=jackmanb@google.com \
--cc=linus@ucla.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.