[PATCH v2 0/2] doc: format-rev: use [synopsis] on code block
- From
- kristofferhaugsbakk@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