[PATCH v2 0/9] doc: interpret-trailers: explain key format

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): kh/doc-trailers

Topic summary: Explain the format of trailer keys (alphanum and
hyphens). This is important to keep in mind so that metadata is not
lost to simple syntax errors. Also replace some terms and define the
important ones upfront.

To that end, an overview of the changes:

• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain
  the “key” format, and add a new example
• Patch 8: Also use the “trailer block” term introduced to the doc in
  patch 5 later in the doc
• Patch 9: document line comment behavior

§ Changes in v2

Here one thing lead to another, mostly because changing one part of
the doc necessitated knock-on changes. An exception though is
the last patch which could be added later/separately.

As for the changes requested after the review on v1:

• Add missing mention of the default separator (:)
• Remove confusing “paint by numbers” reference
• Remove “The hyphens serve as interword separators”. This is a normative
  statement.

  An advisory statement would have been fine. But I see now that I didn’t
  weave that in to this version.
• There was an unclear part:

      we emphasize these two first standalone word mentions.

  Which shouldn’t be a problem now that the context/patch has been
  rewritten.

§ Cc

Linus Arver as the author of the example that this change touches.

This was more relevant on v1.

§ Link to v1

https://lore.kernel.org/git/CV_doc_int-tr_key_format.533@msgid.xyz/#t

[1/9] doc: interpret-trailers: stop fixating on RFC 822
[2/9] doc: interpret-trailers: replace “lines” with “metadata”
[3/9] doc: interpret-trailers: use “metadata” in Name as well
[4/9] doc: interpret-trailers: not just for commit messages
[5/9] doc: interpret-trailers: explain the format after the intro
[6/9] doc: interpret-trailers: explain key format
[7/9] doc: interpret-trailers: add key format example
[8/9] doc: interpret-trailers: commit to “trailer block” term
[9/9] doc: intepret-trailers: document comment line treatment

 Documentation/git-interpret-trailers.adoc | 68 +++++++++++++++++------
 1 file changed, 50 insertions(+), 18 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 92d9c95f9d2..b42f957d666 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -3,7 +3,7 @@ git-interpret-trailers(1)
 
 NAME
 ----
-git-interpret-trailers - Add or parse structured information in commit messages
+git-interpret-trailers - Add or parse metadata in commit messages
 
 SYNOPSIS
 --------
@@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]
 
 DESCRIPTION
 -----------
-Add or parse _trailer_ key-value pairs at the end of the otherwise
-free-form part of a commit message. For example, in the following commit
-message
+Add or parse trailers 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. 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
 
 ------------------------------------------------
 subject
@@ -27,10 +33,7 @@ Signed-off-by: Alice <alice@example.com>
 Signed-off-by: Bob <bob@example.com>
 ------------------------------------------------
 
-the last two lines starting with `Signed-off-by` are trailers. These two
-trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).
-The key must consist of only ASCII alphanumeric characters and hyphens
-(`-`). The hyphens serve as interword separators.
+the last two lines starting with `Signed-off-by` are trailers.
 
 This command reads commit messages from either the
 _<file>_ arguments or the standard input if no _<file>_ is specified.
@@ -84,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.
 
-Existing trailers are extracted from the input by looking for
-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
 least 25% trailers.
-The group must be preceded by one or more empty (or whitespace-only) lines.
-The group must either be at the end of the input or be the last
-non-whitespace lines before a line that starts with `---` (followed by a
-space or the end of the line).
+The trailer block is by definition at the end the the message. The end
+of the message in turn is either (i) at the end of the input, or (ii)
+the last non-whitespace lines before a line that starts with `---`
+(followed by a space or the end of the line).
+
+This command ignores comment lines (see `core.commentString` in
+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
+and `commit-msg` hooks.
 
 When reading trailers, there can be no whitespace before or inside the
 _<key>_, but any number of regular space and tab characters are allowed
@@ -402,6 +411,29 @@ mv "\$1.new" "\$1"
 $ chmod +x .git/hooks/commit-msg
 ------------
 
+* Here we try to to use three different trailer keys. But it fails
+  because two of them are not recognized as trailer keys.
++
+----
+$ cat msg.txt
+subject
+
+Skapad-på: some-branch
+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c
+Reviewed-by: Alice <alice@example.com>
+$ git interpret-trailers --only-trailers <msg.txt
+$
+----
++
+Recall that a trailer key has to consist of only ASCII alphanumeric
+characters and hyphens, and this does not hold for the two first
+supposed trailer keys. And now none are recognized as trailers because
+the candidate trailer block has at least one non-trailer line, even
+though `Reviewed-by` is a valid trailer key. Recall that a trailer block
+has to either (i) be all trailers, or (ii) consist of at least one
+Git-generated or user-configured trailer (and some other conditions).
+And (ii) is not satisfied since we have not configured any trailer keys.
+
 SEE ALSO
 --------
 linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]

base-commit: 5361983c075154725be47b65cca9a2421789e410
-- 
2.53.0.32.gf6228eaf9cc