[PATCH] doc: patch-id: convert to the modern synopsis style

[PATCH] doc: patch-id: convert to the modern synopsis style

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Convert this command documentation to the modern synopsis style based on
similar work.[1] Concretely:

• Change the Synopsis section from `verse` to a `synopsis` block which
  will automatically apply the correct formatting to various elements
  (although this Synopsis is very simple)
• Use backticks (`) for code-like things which will also use the correct
  formatting for interior placeholders (`<orderfile>`)
• Use backticks on options

† 1: E.g.,
     • 026f2e3b (doc: convert git-log to new documentation format,
       2025-07-07)
     • b983aaab (doc: convert git-switch manpage to new synopsis style,
       2025-05-25)
     • 16543967 (doc: convert git-mergetool manpage to new synopsis
       style, 2025-05-25)

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

Notes (series):
    Topic name: kh/patch-id-doc-part-one
    
    Topic summary: The documentation for "git patch-id" has been converted
    to the modern "synopsis" style.
    
    Update git-patch-id(1) to the new synopsis style.  This is done based on
    observing what Jean-Noël Avila has done on other documentation pages.
    
    I don’t know what high-level plans Jean-Noël and the maintainer have for
    the rewrite so I don’t know if posting this update is somehow
    inappropriate in light of that.
    
    § Notes to the maintainer[1]
    
    This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
    patch-id: fix accidental literal blocks, 2025-09-29) merged into
    v2.50.0 (because that’s what the topic is based on).
    
    (is there a “reference” convention for mentioning a topic + commit?)
    
      † 1: Inspired by
           • <cover.1759097191.git.me@ttaylorr.com>
           • SubmittingPatches: guidance for topic names and multi-series efforts
             • <cover.1759873165.git.me@ttaylorr.com>
    
    This is part one of a multi-series effort focusing on this
    documentation page. Technically that intent started with topic
    kh/doc-patch-id-markup-fix, but I published that before I learned
    about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
    So this gets named “part one” in the cover letter (and maybe on the
    topic name).
    
    The current plan for parts 2–5:
    
    2. Various smaller fixups (many small patches/commits)
    3. Mention the two config variables in git-config(1)
    4. Make it more clear that you can feed multiple diffs to this command
    5. An “Examples” section
    
    Why a multi-part series?  It started with the idea of (1) emphasizing
    that this command can take multiple patches, and (2) making an
    Examples. But then I saw other things to fix. And they ought to go
    first... eventually I ended up with many commits or ideas.
    
    I wanted to see if this was easier to review.
    
    • Focus on uncontroversial changes first
    • Make all the series either small, simple/trivial, or both
    • Leave the changes that might spark discussion last; the ones that have
      to do with authoring new paragraphs/sections
    
    (I realize that multi-part series are probably mostly used for
    super-technical changes that take 50+ patches in total and that only
    three people on the list have the time and capacity to review at any
    given point in time.)

 Documentation/git-patch-id.adoc | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index 45da0f27acd..bfbf23f49c4 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
 
 SYNOPSIS
 --------
-[verse]
-'git patch-id' [--stable | --unstable | --verbatim]
+[synopsis]
+git patch-id [--stable | --unstable | --verbatim]
 
 DESCRIPTION
 -----------
@@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same
 
 The main usecase for this command is to look for likely duplicate commits.
 
-When dealing with 'git diff-tree' output, it takes advantage of
+When dealing with `git diff-tree` output, it takes advantage of
 the fact that the patch is prefixed with the object name of the
 commit, and outputs two 40-byte hexadecimal strings.  The first
 string is the patch ID, and the second string is the commit ID.
@@ -30,19 +30,19 @@ This can be used to make a mapping from patch ID to commit ID.
 OPTIONS
 -------
 
---verbatim::
+`--verbatim`::
 	Calculate the patch-id of the input as it is given, do not strip
 	any whitespace.
 +
 This is the default if patchid.verbatim is true.
 
---stable::
+`--stable`::
 	Use a "stable" sum of hashes as the patch ID. With this option:
 +
 --
 - Reordering file diffs that make up a patch does not affect the ID.
   In particular, two patches produced by comparing the same two trees
-  with two different settings for "-O<orderfile>" result in the same
+  with two different settings for `-O<orderfile>` result in the same
   patch ID signature, thereby allowing the computed result to be used
   as a key to index some meta-information about the change between
   the two trees;
@@ -50,7 +50,7 @@ This is the default if patchid.verbatim is true.
 - Result is different from the value produced by git 1.9 and older
   or produced when an "unstable" hash (see --unstable below) is
   configured - even when used on a diff output taken without any use
-  of "-O<orderfile>", thereby making existing databases storing such
+  of `-O<orderfile>", thereby making existing databases storing such
   "unstable" or historical patch-ids unusable.
 
 - All whitespace within the patch is ignored and does not affect the id.
@@ -58,7 +58,7 @@ This is the default if patchid.verbatim is true.
 +
 This is the default if patchid.stable is set to true.
 
---unstable::
+`--unstable`::
 	Use an "unstable" hash as the patch ID. With this option,
 	the result produced is compatible with the patch-id value produced
 	by git 1.9 and older and whitespace is ignored.  Users with pre-existing
-- 
2.51.0.352.g356bc2d8d49

Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Jeff King]

On Thu, Oct 09, 2025 at 10:53:53PM +0200, kristofferhaugsbakk@fastmail.com wrote:

> Convert this command documentation to the modern synopsis style based on
> similar work.[1] Concretely:
> 
> • Change the Synopsis section from `verse` to a `synopsis` block which
>   will automatically apply the correct formatting to various elements
>   (although this Synopsis is very simple)
> • Use backticks (`) for code-like things which will also use the correct
>   formatting for interior placeholders (`<orderfile>`)
> • Use backticks on options

These all look like strict improvements to me. Sadly doc-diff doesn't
show much here because the changes are mostly typographical, so I
eyeballed the HTML output (which does look much nicer).

-Peff

Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Jean-Noël Avila]

Le 09/10/2025 à 22:53, kristofferhaugsbakk@fastmail.com a écrit :
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> Convert this command documentation to the modern synopsis style based on
> similar work.[1] Concretely:
> 
> • Change the Synopsis section from `verse` to a `synopsis` block which
>   will automatically apply the correct formatting to various elements
>   (although this Synopsis is very simple)
> • Use backticks (`) for code-like things which will also use the correct
>   formatting for interior placeholders (`<orderfile>`)
> • Use backticks on options
> 
> † 1: E.g.,
>      • 026f2e3b (doc: convert git-log to new documentation format,
>        2025-07-07)
>      • b983aaab (doc: convert git-switch manpage to new synopsis style,
>        2025-05-25)
>      • 16543967 (doc: convert git-mergetool manpage to new synopsis
>        style, 2025-05-25)
> 
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
> 
> Notes (series):
>     Topic name: kh/patch-id-doc-part-one
>     
>     Topic summary: The documentation for "git patch-id" has been converted
>     to the modern "synopsis" style.
>     
>     Update git-patch-id(1) to the new synopsis style.  This is done based on
>     observing what Jean-Noël Avila has done on other documentation pages.
>     
>     I don’t know what high-level plans Jean-Noël and the maintainer have for
>     the rewrite so I don’t know if posting this update is somehow
>     inappropriate in light of that.
>     
>     § Notes to the maintainer[1]
>     
>     This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
>     patch-id: fix accidental literal blocks, 2025-09-29) merged into
>     v2.50.0 (because that’s what the topic is based on).
>     
>     (is there a “reference” convention for mentioning a topic + commit?)
>     
>       † 1: Inspired by
>            • <cover.1759097191.git.me@ttaylorr.com>
>            • SubmittingPatches: guidance for topic names and multi-series efforts
>              • <cover.1759873165.git.me@ttaylorr.com>
>     
>     This is part one of a multi-series effort focusing on this
>     documentation page. Technically that intent started with topic
>     kh/doc-patch-id-markup-fix, but I published that before I learned
>     about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
>     So this gets named “part one” in the cover letter (and maybe on the
>     topic name).
>     
>     The current plan for parts 2–5:
>     
>     2. Various smaller fixups (many small patches/commits)
>     3. Mention the two config variables in git-config(1)
>     4. Make it more clear that you can feed multiple diffs to this command
>     5. An “Examples” section
>     
>     Why a multi-part series?  It started with the idea of (1) emphasizing
>     that this command can take multiple patches, and (2) making an
>     Examples. But then I saw other things to fix. And they ought to go
>     first... eventually I ended up with many commits or ideas.
>     
>     I wanted to see if this was easier to review.
>     
>     • Focus on uncontroversial changes first
>     • Make all the series either small, simple/trivial, or both
>     • Leave the changes that might spark discussion last; the ones that have
>       to do with authoring new paragraphs/sections
>     
>     (I realize that multi-part series are probably mostly used for
>     super-technical changes that take 50+ patches in total and that only
>     three people on the list have the time and capacity to review at any
>     given point in time.)
> 
>  Documentation/git-patch-id.adoc | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
> index 45da0f27acd..bfbf23f49c4 100644
> --- a/Documentation/git-patch-id.adoc
> +++ b/Documentation/git-patch-id.adoc
> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
>  
>  SYNOPSIS
>  --------
> -[verse]
> -'git patch-id' [--stable | --unstable | --verbatim]
> +[synopsis]
> +git patch-id [--stable | --unstable | --verbatim]
>  
>  DESCRIPTION
>  -----------
> @@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same
>  
>  The main usecase for this command is to look for likely duplicate commits.
>  
> -When dealing with 'git diff-tree' output, it takes advantage of
> +When dealing with `git diff-tree` output, it takes advantage of
>  the fact that the patch is prefixed with the object name of the
>  commit, and outputs two 40-byte hexadecimal strings.  The first
>  string is the patch ID, and the second string is the commit ID.
> @@ -30,19 +30,19 @@ This can be used to make a mapping from patch ID to commit ID.
>  OPTIONS
>  -------
>  
> ---verbatim::
> +`--verbatim`::
>  	Calculate the patch-id of the input as it is given, do not strip
>  	any whitespace.
>  +
>  This is the default if patchid.verbatim is true.

We also format config names so here `patchid.verbatim`

>  
> ---stable::
> +`--stable`::
>  	Use a "stable" sum of hashes as the patch ID. With this option:
>  +
>  --
>  - Reordering file diffs that make up a patch does not affect the ID.
>    In particular, two patches produced by comparing the same two trees
> -  with two different settings for "-O<orderfile>" result in the same
> +  with two different settings for `-O<orderfile>` result in the same
>    patch ID signature, thereby allowing the computed result to be used
>    as a key to index some meta-information about the change between
>    the two trees;
> @@ -50,7 +50,7 @@ This is the default if patchid.verbatim is true.
>  - Result is different from the value produced by git 1.9 and older
>    or produced when an "unstable" hash (see --unstable below) is


here also "see `--unstable` below"

>    configured - even when used on a diff output taken without any use
> -  of "-O<orderfile>", thereby making existing databases storing such
> +  of `-O<orderfile>", thereby making existing databases storing such
>    "unstable" or historical patch-ids unusable.
>  
>  - All whitespace within the patch is ignored and does not affect the id.
> @@ -58,7 +58,7 @@ This is the default if patchid.verbatim is true.
>  +
>  This is the default if patchid.stable is set to true.

`patchid.stable`

>  
> ---unstable::
> +`--unstable`::
>  	Use an "unstable" hash as the patch ID. With this option,
>  	the result produced is compatible with the patch-id value produced
>  	by git 1.9 and older and whitespace is ignored.  Users with pre-existing

Thanks for jumping in the synopsis squad bandwagon!

Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

>     This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
>     patch-id: fix accidental literal blocks, 2025-09-29) merged into
>     v2.50.0 (because that’s what the topic is based on).
>     
>     (is there a “reference” convention for mentioning a topic + commit?)

The above is perfectly understandable.

>     This is part one of a multi-series effort focusing on this
>     documentation page. Technically that intent started with topic
>     kh/doc-patch-id-markup-fix, but I published that before I learned
>     about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
>     So this gets named “part one” in the cover letter (and maybe on the
>     topic name).
>     
>     The current plan for parts 2–5:
>     
>     2. Various smaller fixups (many small patches/commits)
>     3. Mention the two config variables in git-config(1)
>     4. Make it more clear that you can feed multiple diffs to this command
>     5. An “Examples” section

Quite honestly, this smells like making a mountain out of a
molehill.  5-patch topic that focuses on improving a single
documentation page is nothing unusual, but it is very unusual and
awkward to handle for a topic that focuses on improving a single
documentation page is spread across 5 separate topics, each building
on top of the previous one.

>     Why a multi-part series?  It started with the idea of (1) emphasizing
>     that this command can take multiple patches, and (2) making an
>     Examples. But then I saw other things to fix. And they ought to go
>     first... eventually I ended up with many commits or ideas.

Perhaps then after you built up the final shape, you'd need time to
ruminate over it and possibly reorganize to find the best order and
organization to present it as a N-patch single series?  Typically, a
collection of thoughts presented in the order they came to one's mind
is much harder to judge, relative to an effort to tell a coherent story
that moves to a goal.

But we'll see.

Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Kristoffer Haugsbakk]

On Fri, Oct 10, 2025, at 08:48, Jean-Noël Avila wrote:
>[snip feedback]

Thank you.  I’ve updated for v2.

>
>>
>> ---unstable::
>> +`--unstable`::
>>  	Use an "unstable" hash as the patch ID. With this option,
>>  	the result produced is compatible with the patch-id value produced
>>  	by git 1.9 and older and whitespace is ignored.  Users with pre-existing
>
> Thanks for jumping in the synopsis squad bandwagon!

:)

Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Kristoffer Haugsbakk]

On Fri, Oct 10, 2025, at 07:06, Jeff King wrote:
> On Thu, Oct 09, 2025 at 10:53:53PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>
>> Convert this command documentation to the modern synopsis style based on
>> similar work.[1] Concretely:
>>
>> • Change the Synopsis section from `verse` to a `synopsis` block which
>>   will automatically apply the correct formatting to various elements
>>   (although this Synopsis is very simple)
>> • Use backticks (`) for code-like things which will also use the correct
>>   formatting for interior placeholders (`<orderfile>`)
>> • Use backticks on options
>
> These all look like strict improvements to me. Sadly doc-diff doesn't
> show much here because the changes are mostly typographical, so I
> eyeballed the HTML output (which does look much nicer).

Thanks for testing!

-- 
Kristoffer

[PATCH v2] doc: patch-id: convert to the modern synopsis style

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Convert this command documentation to the modern synopsis style based on
similar work.[1] Concretely:

• Change the Synopsis section from `verse` to a `synopsis` block which
  will automatically apply the correct formatting to various elements
  (although this Synopsis is very simple)
• Use backticks (`) for code-like things which will also use the correct
  formatting for interior placeholders (`<orderfile>`)
• Use inline-verbatim on options listing

† 1: E.g.,
     • 026f2e3b (doc: convert git-log to new documentation format,
       2025-07-07)
     • b983aaab (doc: convert git-switch manpage to new synopsis style,
       2025-05-25)
     • 16543967 (doc: convert git-mergetool manpage to new synopsis
       style, 2025-05-25)

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

Notes (series):
    Topic name (applied): kh/doc-patch-id-1
    
    Topic summary: The documentation for "git patch-id" has been converted
    to the modern "synopsis" style.
    
    Update git-patch-id(1) to the new synopsis style.  This is done based on
    observing what Jean-Noël Avila has done on other documentation pages.
    
    I don’t know what high-level plans Jean-Noël and the maintainer have for
    the rewrite so I don’t know if posting this update is somehow
    inappropriate in light of that.
    
    § Changes in v2
    
    Add more inline-verbatim (`) based on feedback from Jean-Noël.  Details:
    
    • More inline-verbatim markup
      • From feedback
      • Also: on config value (`true`)
    • Tweak commit message; refer to “options listing” for the left-flushed
      options to distinguish from running text
    • Fix mistake from v1 in markup for `-O<orderfile>`
    
    § Notes to the maintainer[1] (unchanged in v2)
    
    This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
    patch-id: fix accidental literal blocks, 2025-09-29) merged into
    v2.50.0 (because that’s what the topic is based on).
    
    (is there a “reference” convention for mentioning a topic + commit?)
    
      † 1: Inspired by
           • <cover.1759097191.git.me@ttaylorr.com>
           • SubmittingPatches: guidance for topic names and multi-series efforts
             • <cover.1759873165.git.me@ttaylorr.com>
    
    This is part one of a multi-series effort focusing on this
    documentation page. Technically that intent started with topic
    kh/doc-patch-id-markup-fix, but I published that before I learned
    about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
    So this gets named “part one” in the cover letter (and maybe on the
    topic name).
    
    The current plan for parts 2–5:
    
    2. Various smaller fixups (many small patches/commits)
    3. Mention the two config variables in git-config(1)
    4. Make it more clear that you can feed multiple diffs to this command
    5. An “Examples” section
    
    Why a multi-part series?  It started with the idea of (1) emphasizing
    that this command can take multiple patches, and (2) making an
    Examples. But then I saw other things to fix. And they ought to go
    first... eventually I ended up with many commits or ideas.
    
    I wanted to see if this was easier to review.
    
    • Focus on uncontroversial changes first
    • Make all the series either small, simple/trivial, or both
    • Leave the changes that might spark discussion last; the ones that have
      to do with authoring new paragraphs/sections
    
    (I realize that multi-part series are probably mostly used for
    super-technical changes that take 50+ patches in total and that only
    three people on the list have the time and capacity to review at any
    given point in time.)

 Documentation/git-patch-id.adoc | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index 45da0f27acd..92a1af36a27 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
 
 SYNOPSIS
 --------
-[verse]
-'git patch-id' [--stable | --unstable | --verbatim]
+[synopsis]
+git patch-id [--stable | --unstable | --verbatim]
 
 DESCRIPTION
 -----------
@@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same
 
 The main usecase for this command is to look for likely duplicate commits.
 
-When dealing with 'git diff-tree' output, it takes advantage of
+When dealing with `git diff-tree` output, it takes advantage of
 the fact that the patch is prefixed with the object name of the
 commit, and outputs two 40-byte hexadecimal strings.  The first
 string is the patch ID, and the second string is the commit ID.
@@ -30,35 +30,35 @@ This can be used to make a mapping from patch ID to commit ID.
 OPTIONS
 -------
 
---verbatim::
+`--verbatim`::
 	Calculate the patch-id of the input as it is given, do not strip
 	any whitespace.
 +
-This is the default if patchid.verbatim is true.
+This is the default if `patchid.verbatim` is `true`.
 
---stable::
+`--stable`::
 	Use a "stable" sum of hashes as the patch ID. With this option:
 +
 --
 - Reordering file diffs that make up a patch does not affect the ID.
   In particular, two patches produced by comparing the same two trees
-  with two different settings for "-O<orderfile>" result in the same
+  with two different settings for `-O<orderfile>` result in the same
   patch ID signature, thereby allowing the computed result to be used
   as a key to index some meta-information about the change between
   the two trees;
 
 - Result is different from the value produced by git 1.9 and older
-  or produced when an "unstable" hash (see --unstable below) is
+  or produced when an "unstable" hash (see `--unstable` below) is
   configured - even when used on a diff output taken without any use
-  of "-O<orderfile>", thereby making existing databases storing such
+  of `-O<orderfile>`, thereby making existing databases storing such
   "unstable" or historical patch-ids unusable.
 
 - All whitespace within the patch is ignored and does not affect the id.
 --
 +
-This is the default if patchid.stable is set to true.
+This is the default if `patchid.stable` is set to `true`.
 
---unstable::
+`--unstable`::
 	Use an "unstable" hash as the patch ID. With this option,
 	the result produced is compatible with the patch-id value produced
 	by git 1.9 and older and whitespace is ignored.  Users with pre-existing

Interdiff against v1:
  diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
  index bfbf23f49c4..92a1af36a27 100644
  --- a/Documentation/git-patch-id.adoc
  +++ b/Documentation/git-patch-id.adoc
  @@ -34,7 +34,7 @@ OPTIONS
   	Calculate the patch-id of the input as it is given, do not strip
   	any whitespace.
   +
  -This is the default if patchid.verbatim is true.
  +This is the default if `patchid.verbatim` is `true`.
   
   `--stable`::
   	Use a "stable" sum of hashes as the patch ID. With this option:
  @@ -48,15 +48,15 @@ This is the default if patchid.verbatim is true.
     the two trees;
   
   - Result is different from the value produced by git 1.9 and older
  -  or produced when an "unstable" hash (see --unstable below) is
  +  or produced when an "unstable" hash (see `--unstable` below) is
     configured - even when used on a diff output taken without any use
  -  of `-O<orderfile>", thereby making existing databases storing such
  +  of `-O<orderfile>`, thereby making existing databases storing such
     "unstable" or historical patch-ids unusable.
   
   - All whitespace within the patch is ignored and does not affect the id.
   --
   +
  -This is the default if patchid.stable is set to true.
  +This is the default if `patchid.stable` is set to `true`.
   
   `--unstable`::
   	Use an "unstable" hash as the patch ID. With this option,

Range-diff against v1:
1:  978261e3be4 ! 1:  38645ea253c doc: patch-id: convert to the modern synopsis style
    @@ Commit message
           (although this Synopsis is very simple)
         • Use backticks (`) for code-like things which will also use the correct
           formatting for interior placeholders (`<orderfile>`)
    -    • Use backticks on options
    +    • Use inline-verbatim on options listing
     
         † 1: E.g.,
              • 026f2e3b (doc: convert git-log to new documentation format,
    @@ Commit message
     
     
      ## Notes (series) ##
    -    Topic name: kh/patch-id-doc-part-one
    +    Topic name (applied): kh/doc-patch-id-1
     
         Topic summary: The documentation for "git patch-id" has been converted
         to the modern "synopsis" style.
    @@ Notes (series)
         the rewrite so I don’t know if posting this update is somehow
         inappropriate in light of that.
     
    -    § Notes to the maintainer[1]
    +    § Changes in v2
    +
    +    Add more inline-verbatim (`) based on feedback from Jean-Noël.  Details:
    +
    +    • More inline-verbatim markup
    +      • From feedback
    +      • Also: on config value (`true`)
    +    • Tweak commit message; refer to “options listing” for the left-flushed
    +      options to distinguish from running text
    +    • Fix mistake from v1 in markup for `-O<orderfile>`
    +
    +    § Notes to the maintainer[1] (unchanged in v2)
     
         This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:
         patch-id: fix accidental literal blocks, 2025-09-29) merged into
    @@ Documentation/git-patch-id.adoc: This can be used to make a mapping from patch I
      	Calculate the patch-id of the input as it is given, do not strip
      	any whitespace.
      +
    - This is the default if patchid.verbatim is true.
    +-This is the default if patchid.verbatim is true.
    ++This is the default if `patchid.verbatim` is `true`.
      
     ---stable::
     +`--stable`::
    @@ Documentation/git-patch-id.adoc: This can be used to make a mapping from patch I
        patch ID signature, thereby allowing the computed result to be used
        as a key to index some meta-information about the change between
        the two trees;
    -@@ Documentation/git-patch-id.adoc: This is the default if patchid.verbatim is true.
    + 
      - Result is different from the value produced by git 1.9 and older
    -   or produced when an "unstable" hash (see --unstable below) is
    +-  or produced when an "unstable" hash (see --unstable below) is
    ++  or produced when an "unstable" hash (see `--unstable` below) is
        configured - even when used on a diff output taken without any use
     -  of "-O<orderfile>", thereby making existing databases storing such
    -+  of `-O<orderfile>", thereby making existing databases storing such
    ++  of `-O<orderfile>`, thereby making existing databases storing such
        "unstable" or historical patch-ids unusable.
      
      - All whitespace within the patch is ignored and does not affect the id.
    -@@ Documentation/git-patch-id.adoc: This is the default if patchid.verbatim is true.
    + --
      +
    - This is the default if patchid.stable is set to true.
    +-This is the default if patchid.stable is set to true.
    ++This is the default if `patchid.stable` is set to `true`.
      
     ---unstable::
     +`--unstable`::
-- 
2.51.0.352.g356bc2d8d49

Re: [PATCH] doc: patch-id: convert to the modern synopsis style

[Kristoffer Haugsbakk]

On Fri, Oct 10, 2025, at 10:50, Junio C Hamano wrote:
>>     This is part one of a multi-series effort focusing on this
>>     documentation page. Technically that intent started with topic
>>     kh/doc-patch-id-markup-fix, but I published that before I learned
>>     about the idea presented in <cover.1759873165.git.me@ttaylorr.com>.
>>     So this gets named “part one” in the cover letter (and maybe on the
>>     topic name).
>>
>>     The current plan for parts 2–5:
>>
>>     2. Various smaller fixups (many small patches/commits)
>>     3. Mention the two config variables in git-config(1)
>>     4. Make it more clear that you can feed multiple diffs to this command
>>     5. An “Examples” section
>
> Quite honestly, this smells like making a mountain out of a
> molehill.

Got it.

> 5-patch topic that focuses on improving a single
> documentation page is nothing unusual, but it is very unusual and
> awkward to handle for a topic that focuses on improving a single
> documentation page is spread across 5 separate topics, each building
> on top of the previous one.

To be sure: I’ll abort the plan if it turns out to be worse for the
reviewers.

I can make the following amemdment right now: after this current topic I
will wait until it graduates to `master` instead of basing the next
topic on the merge to `next`.

Either that or everything that I plan to send gets sent in the next
topic.

>
>>     Why a multi-part series?  It started with the idea of (1) emphasizing
>>     that this command can take multiple patches, and (2) making an
>>     Examples. But then I saw other things to fix. And they ought to go
>>     first... eventually I ended up with many commits or ideas.
>
> Perhaps then after you built up the final shape, you'd need time to
> ruminate over it and possibly reorganize to find the best order and
> organization to present it as a N-patch single series?  Typically, a
> collection of thoughts presented in the order they came to one's mind
> is much harder to judge, relative to an effort to tell a coherent story
> that moves to a goal.

That’s a good point.  I will rather scrap things and recreate them if I
come up with a better order rather than committing to the existing one.

Re: [PATCH v2] doc: patch-id: convert to the modern synopsis style

[Eric Sunshine]

On Mon, Oct 13, 2025 at 12:28 PM <kristofferhaugsbakk@fastmail.com> wrote:
> Convert this command documentation to the modern synopsis style based on
> similar work.[1] Concretely: [...]
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
> ---unstable::
> +`--unstable`::
>         Use an "unstable" hash as the patch ID. With this option,
>         the result produced is compatible with the patch-id value produced
>         by git 1.9 and older and whitespace is ignored.  Users with pre-existing

Is the mix of "patch ID" and "patch-id" intentional? If so, should
"patch-id" be wrapped in backticks?

Re: [PATCH v2] doc: patch-id: convert to the modern synopsis style

[Kristoffer Haugsbakk]

On Mon, Oct 13, 2025, at 18:53, Eric Sunshine wrote:
> On Mon, Oct 13, 2025 at 12:28 PM <kristofferhaugsbakk@fastmail.com> wrote:
>> Convert this command documentation to the modern synopsis style based on
>> similar work.[1] Concretely: [...]
>>
>> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>> ---
>> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
>> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
>> ---unstable::
>> +`--unstable`::
>>         Use an "unstable" hash as the patch ID. With this option,
>>         the result produced is compatible with the patch-id value produced
>>         by git 1.9 and older and whitespace is ignored.  Users with pre-existing
>
> Is the mix of "patch ID" and "patch-id" intentional? If so, should
> "patch-id" be wrapped in backticks?

I originally assumed that “patch-id” here meant “patch ID` but now I’m
not sure (what was intended).

The way I read it then made me change all of these “patch-id” to “patch
ID” for consistency.  That’s a future change/topic.