From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This code block uses the placeholder `<subject>`. Let’s highlight this placeholder properly by using the `synopsis` block definition which was introduced in a34d1d53 (doc: convert git-show to synopsis style, 2026-02-06).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name: kh/doc-format-rev-1

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This code block uses the placeholder `<subject>`. Let’s highlight this placeholder properly by using the `synopsis` block definition which was introduced in a34d1d53 (doc: convert git-show to synopsis style, 2026-02-06).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name: kh/doc-format-rev-1

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

On Mon, Aug 10, 2026 at 06:58:05PM +0200, kristofferhaugsbakk@fastmail.com wrote:

I'm not particularly knowledgeable in AsciiDoc, I only picked it up because nobody else did. So please consider me even more clueless than I typically am :)

Hm. I was always under the impression that `[synopsis]` is used as exactly that, so it surprises me a bit that you want to use it for a random block that doesn't look like one at all. But going through our docs (like for example git-blame(1)) I see that we also do this for other non-synopsis-like blocks, so maybe this is fine?

There's probably a good reason for this, but can't we instead just use backticks to make `<subject>` render the exact same as four lines above?

Thanks!

Patrick

On Tue, Aug 11, 2026, at 14:32, Patrick Steinhardt wrote:

Thanks for taking a look.

To be clear, it’s not this kind of [synopsis]:

    [synopsis]
    git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]

This [synopsis] is for a code block to highlight <subject> just like how <subject> is highlighted in running text when using (_) or (`).

It’s a code block and the literal text is supposed to use quotation marks.

Well. I wrote the text to mean that subject is supposed to be quoted. So perhaps I should have written `"%s"` instead of `"%s"`:

     i.e. the format `"%s"` would transform some commit object name to
     `"<subject>"` without any termination. Like this: ...

;-)

On Tue, Aug 11, 2026 at 06:23:18PM +0200, Kristoffer Haugsbakk wrote:

Ah, so we have different kinds of synopsis depending on what it applies to?

Makes sense, thanks!

Patrick

On Tue, Aug 11, 2026, at 18:27, Patrick Steinhardt wrote:

Yeah, that must be it. To be honest I had neglected to consider that the command description part uses the same syntax already... x)

Thank you.

On Tue, Aug 11, 2026, at 18:23, Kristoffer Haugsbakk wrote:

I might do a re-roll with a change to use "". I’ll see how it looks first.

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:

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We first talk about just `%s`, but then show the result with quotes. That is inconsistent. Let’s use quotes both in the format as well as in the result.

The implied input here, which is not spelled out for brevity, is:

    Did we not fix this in <commit object name>?

Which is then supposed to be formatted to `"<subject>"`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • [new]
    • I wanted to add this after spotting the problem in [1]
      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t

 Documentation/git-format-rev.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This code block uses the placeholder `<subject>`. Let’s highlight this placeholder properly by using the `synopsis` block definition which was 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>
---

Notes (series):
    v2:
    • Add a paragraph to contrast synopsis code blocks with synopsis
      command description after talk with Patrick on v1[1]
    
      🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

On Thu, Aug 13, 2026 at 11:57:36AM +0200, kristofferhaugsbakk@fastmail.com wrote:

Thanks for the additional reference to the above commit. That helps, and you can see that as part of the commit we have similar changes to our docs like you do them in your patch.

So I'm happy with this version, thanks!

Patrick

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 v3

• Patch 2/2: Add Ack

§ Cc

(See v2)

§ Link to v2

https://lore.kernel.org/git/V2_CV_synopsis_block.b4a@msgid.xyz/

[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 v2:
Range-diff against v2:
1:  c82aec7969f = 1:  c82aec7969f doc: format-rev: quote subject placeholder before and after
2:  f528d7e9dcd ! 2:  b9a93c83c88 doc: format-rev: use [synopsis] on code block
    @@ Commit message
             [verse]
             'git name-rev' [...]
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-format-rev.adoc ##

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We first talk about just `%s`, but then show the result with quotes. That is inconsistent. Let’s use quotes both in the format as well as in the result.

The implied input here, which is not spelled out for brevity, is:

    Did we not fix this in <commit object name>?

Which is then supposed to be formatted to `"<subject>"`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • [new]
    • I wanted to add this after spotting the problem in [1]
      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t

 Documentation/git-format-rev.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This code block uses the placeholder `<subject>`. Let’s highlight this placeholder properly by using the `synopsis` block definition which was 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' [...]

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3: add Ack: https://lore.kernel.org/git/an2Wwe4ytilGoyHz@pks.im/
    v2:
    • Add a paragraph to contrast synopsis code blocks with synopsis
      command description after talk with Patrick on v1[1]
    
      🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/

 Documentation/git-format-rev.adoc | 1 +
 1 file changed, 1 insertion(+)

kristofferhaugsbakk@fastmail.com writes:

Has this been tested with both AsciiDoc and AsciiDoctor?

  https://github.com/git/git/actions/runs/31751206776/job/94617158587#step:4:4886

Curiously, it does not fail for me locally (by default my builds use AsciiDoctor).

On Fri, Aug 14, 2026, at 03:01, Junio C Hamano wrote:

Nope. :/

My change uses a code block:

    [synopsis]
    ----
    ...
    ----

But the ones in `pretty-formats.adoc` use open blocks:

    [synopsis]
    --
    ...
    --

I’ll do some better testing next.

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

Thanks.

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): kh/format-rev-doc-synopsis

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

§ Changes in v4

Sorry about not reading carefully. An open block is not a code block.

(copied from the patch note)

Fix block: use open block, not code block.[1] This is what was done for the synopsis blocks in commit a34d1d53, the commit mentioned here. I have tested this with what I believe are the use-asciidoc (tool) and use-asciidoctor (tool):

    make doc
    make USE_ASCIIDOCTOR=1 doc

And they didn’t give any warnings. And they produced the correct result.

  🔗 1: https://lore.kernel.org/git/xmqqfr0hqzvl.fsf@gitster.g/

Rewrite or flesh out the commit message to reflect this newfound knowledge.

Also remove the Ack since this change invalidates it.

§ Cc

(See v2)

§ Link to v3

https://lore.kernel.org/git/V3_CV_synopsis_block.b64@msgid.xyz/

[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 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

Interdiff against v3:

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We first talk about just `%s`, but then show the result with quotes. That is inconsistent. Let’s use quotes both in the format as well as in the result.

The implied input here, which is not spelled out for brevity, is:

    Did we not fix this in <commit object name>?

Which is then supposed to be formatted to `"<subject>"`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • [new]
    • I wanted to add this after spotting the problem in [1]
      🔗 1: https://lore.kernel.org/git/a495b0d8-b735-4ae4-8cbe-56fd42bbbd3f@app.fastmail.com/#t

 Documentation/git-format-rev.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This code block uses the placeholder `<subject>`. Let’s highlight this placeholder properly by using the `synopsis` open block definition which was introduced in a34d1d53 (doc: convert git-show to synopsis style, 2026-02-06). This renders the block like a code block but with emphasis styling on placeholders, just like inline-verbatim (`) in running text.

Yes, note that open 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>
---

Notes (series):
    v4:
    • Fix block: use open block, not code block.[1] This is what was
      done for the synopsis blocks in commit a34d1d53, the commit
      mentioned here. I have tested this with what I believe are the
      use-asciidoc (tool) and use-asciidoctor (tool):
    
          make doc
          make USE_ASCIIDOCTOR=1 doc
    
      And they didn’t give any warnings. And they produced the correct
      result.
    
      🔗 1: https://lore.kernel.org/git/xmqqfr0hqzvl.fsf@gitster.g/
    • Msg: Rewrite or flesh out the message to reflect this newfound
      knowledge
    • Remove Ack from the previous round since I had to make these
      changes
    ---
    v3: add Ack: https://lore.kernel.org/git/an2Wwe4ytilGoyHz@pks.im/
    v2:
    • Add a paragraph to contrast synopsis code blocks with synopsis
      command description after talk with Patrick on v1[1]
    
      🔗 1: https://lore.kernel.org/git/ansWZxZ6lB0tYIJD@pks.im/

 Documentation/git-format-rev.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

kristofferhaugsbakk@fastmail.com writes:

Hopefully this is now ready for 'next'.

Thanks.