[PATCH] doc: patch-id: convert to the modern synopsis style
- From
- kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
- Date
- Oct 9, 2025, 20:53 UTC
- Message-ID
- <978261e3be4.1760043036.git.code@khaugsbakk.name>
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