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

From

Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>

Date

Oct 13, 2025, 15:42 UTC

Message-ID

<v2-38645ea253c.1760369708.git.code@khaugsbakk.name>

In-Reply-To

<978261e3be4.1760043036.git.code@khaugsbakk.name>

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

• 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