git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2 0/2] doc: format-rev: use [synopsis] on code block

From
Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date
Aug 13, 2026, 09:57 UTC
Message-ID
<V2_CV_synopsis_block.b4a@msgid.xyz>
In-Reply-To
<synopsis_block.af9@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name: kh/doc-format-rev-1

Topic summary: Use '[synopsis]' on code block in order to highlight placeholder properly. Also quote the subject consistently.

§ Changes in v2
See the patches themselves for details.
• Patch 1/2: New; see “Well.”: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t
• Patch 2/2: Add a new commit message paragraph to avoid confusion on
  `[synopsis]` on-command vs. on-code-block
§ Cc

I’ve added a soft Cc (?) on Jean-Noël Avila because I added more “technical” discussion to the commit message. Hopefully it is formulated correctly.

[1/2] doc: format-rev: quote subject placeholder before and after [2/2] doc: format-rev: use [synopsis] on code block

 Documentation/git-format-rev.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Interdiff against v1:
diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc
index 836ba4b0c24..d6c2e4aec1a 100644
--- a/Documentation/git-format-rev.adoc
+++ b/Documentation/git-format-rev.adoc
@@ -93,8 +93,8 @@ acts as a _terminator_, not a _separator_. In other words, the final
 line or record is also terminated by the terminator character.
 
 The mode `--stdin-mode=text` replaces each object name with the
-formatted commit, i.e. the format `%s` would transform some commit
-object name to `<subject>` without any termination. Like this:
+formatted commit, i.e. the format `"%s"` would transform some commit
+object name to `"<subject>"` without any termination. Like this:
 
 [synopsis]
 ----
Range-diff against v1:
-:  ----------- > 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after
1:  652198740e3 ! 2:  f528d7e9dcd doc: format-rev: use [synopsis] on code block
    @@ Commit message
         introduced in a34d1d53 (doc: convert git-show to synopsis style,
         2026-02-06).
     
    +    Yes, note that code blocks since commit a34d1d53 can, on synopsis-style
    +    docs like this one, be immediately preceded by `[synopsis]`, just like
    +    the command synopsis is:
    +
    +        [synopsis]
    +        (EXPERIMENTAL!) git format-rev - [...]
    +
    +    Cf. verse-style:
    +
    +        [verse]
    +        'git name-rev' [...]
    +
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-format-rev.adoc ##
     @@ Documentation/git-format-rev.adoc: The mode `--stdin-mode=text` replaces each object name with the
    - formatted commit, i.e. the format `%s` would transform some commit
    - object name to `<subject>` without any termination. Like this:
    + formatted commit, i.e. the format `"%s"` would transform some commit
    + object name to `"<subject>"` without any termination. Like this:
      
     +[synopsis]
      ----

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
-- 
2.54.0.22.g9e26862b904
Previous: Kristoffer HaugsbakkNext: kristofferhaugsbakk@fastmail.com
Message 8 of 21 in “doc: format-rev: use [synopsis] on code block”
  1. doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  2. doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 10, 2026
  3. Patrick SteinhardtAug 11, 2026
  4. Kristoffer HaugsbakkAug 11, 2026
  5. Patrick SteinhardtAug 11, 2026
  6. Kristoffer HaugsbakkAug 11, 2026
  7. Kristoffer HaugsbakkAug 11, 2026
  8. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  9. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  10. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  11. Patrick SteinhardtAug 13, 2026
  12. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  13. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  14. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 13, 2026
  15. Junio C HamanoAug 14, 2026
  16. Kristoffer HaugsbakkAug 14, 2026
  17. Junio C HamanoAug 14, 2026
  18. 0/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  19. 1/2 doc: format-rev: quote subject placeholder before and afterkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  20. 2/2 doc: format-rev: use [synopsis] on code blockkristofferhaugsbakk@fastmail.com, Aug 17, 2026
  21. Junio C HamanoAug 17, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.