[PATCH v4 06/11] doc: interpret-trailers: explain key format
- From
- kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
- Date
- Jul 30, 2026, 09:18 UTC
- Message-ID
- <V4_trailer_key_format.ae8@msgid.xyz>
- In-Reply-To
- <V4_CV_doc_int-tr_key_format.ae2@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
A trailer key must consist of ASCII alphanumeric characters and hyphens *only*. Let’s document it explicitly instead of relying on readers being conservative and only basing their trailer keys on the documentation examples.[1]
The previous commit provided us with an appropriate paragraph to describe the key format.
† 1: Technically they would then miss out on using digits in them since
all of the example keys just use letters and hyphensReported-by: Brendan Jackman <jackmanb@google.com> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> ---
Notes (series):
v2:
• PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/
• Remove the “paint by numbers” reference after review (unclear)
• Add apropos footnote
• Tweak the paragraph about how we now have a context to describe
this format
v1: [had a note about code spelunking (isalnum(3))]Documentation/git-interpret-trailers.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc index 109059f11ed..fb503cbe952 100644 --- a/Documentation/git-interpret-trailers.adoc +++ b/Documentation/git-interpret-trailers.adoc @@ -18,7 +18,8 @@ Add or parse trailer metadata at the end of the otherwise free-form part of a commit message, or any other kind of text. A _trailer_ in its simplest form is a key-value pair with a colon as a -separator. A _trailer block_ consists of one or more trailers. The +separator. The _key_ consists of ASCII alphanumeric characters and +hyphens (`-`). A _trailer block_ consists of one or more trailers. The trailer block needs to be preceded by a blank line, where a _blank line_ is either an empty or a whitespace-only line. For example, in the following commit message
-- 2.54.0.22.g9e26862b904