[PATCH v4 11/11] doc: interpret-trailers: document comment line treatment

From: Kristoffer Haugsbakk <[email protected]>

Comment lines have always been ignored but this is not documented.

The primary motivation here is to reasonably complete in the
documentation of how trailers are parsed; this is after all the only
documentation page that documents this format. However, and going beyond
that point, we could imagine that someone would want to use this format
outside a commit (or tag) message context, like say in Git notes.

On the other hand, it seems far-fetched that someone would be caught
off guard by this considering that comment characters/strings are not
likely to be alphanumeric,[1] which would mean that these comment lines
would be treated as non-trailer lines if they were *not* detected and
removed as comment lines.

† 1: A notable exception is that Jujutsu VCS uses `JJ:` as
     the comment string

Signed-off-by: Kristoffer Haugsbakk <[email protected]>
---

Notes (series):
    v4:
    • Msg: rewrite motivation for documenting this. The motivation is
      not super solid, but it reflects my own ambiguity on the matter,
      so to speak; I think we ought to be very thorough about
      documenting the format, while making sure to not use the main text
      to exhaustively lay it all out. The information should be
      somewhere in this doc. But not in your face.
    • Msg: Add “(or tag) message”. See patch “not just for commit
      messages” where trailer support for tag messages are mentioned.
    
    ---
    
    v3:
    • Msg: finally fix area
    • Demote this point to its own “other rules” section, out of the main
      running text. It is not important enough for the main text.
    • Since writing this I have realized that we can go into that long
    
         # ----- >8 ----
    
      Commit message separator scissor line, maybe other things. But I stop
      short here. These things are even less likely to become a problem for
      anyone. And maybe we’ll add them later?
    
    v2: [new]

 Documentation/git-interpret-trailers.adoc | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index ac59ef51f80..b4988d39eab 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and
   newlines in it.
 ------------------------------------------------
 
+OTHER RULES
+-----------
+
+What was covered in the previous section are the rules that are relevant
+for regular use. The following points are included for completeness.
+
+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.
+
 OPTIONS
 -------
 `--in-place`::
-- 
2.54.0.22.g9e26862b904