{"thread":{"id":"64285","subject":"[PATCH] doc: patch-id: convert to the modern synopsis style","startedAt":"2025-10-09T20:54:44Z","lastAt":"2025-10-14T20:47:09Z","messageCount":10,"participants":["kristofferhaugsbakk@fastmail.com","Jeff King","Jean-Noël Avila","Junio C Hamano","Kristoffer Haugsbakk","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"528402","messageId":"978261e3be4.1760043036.git.code@khaugsbakk.name","threadId":"64285","inReplyTo":null,"subject":"[PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-09T20:53:53Z","receivedAt":"2025-10-09T20:54:44Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nConvert this command documentation to the modern synopsis style based on\nsimilar work.[1] Concretely:\n\n• Change the Synopsis section from `verse` to a `synopsis` block which\n will automatically apply the correct formatting to various elements\n (although this Synopsis is very simple)\n• Use backticks (`) for code-like things which will also use the correct\n formatting for interior placeholders (``)\n• Use backticks on options\n\n† 1: E.g.,\n • 026f2e3b (doc: convert git-log to new documentation format,\n 2025-07-07)\n • b983aaab (doc: convert git-switch manpage to new synopsis style,\n 2025-05-25)\n • 16543967 (doc: convert git-mergetool manpage to new synopsis\n style, 2025-05-25)\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n Topic name: kh/patch-id-doc-part-one\n \n Topic summary: The documentation for \"git patch-id\" has been converted\n to the modern \"synopsis\" style.\n \n Update git-patch-id(1) to the new synopsis style. This is done based on\n observing what Jean-Noël Avila has done on other documentation pages.\n \n I don’t know what high-level plans Jean-Noël and the maintainer have for\n the rewrite so I don’t know if posting this update is somehow\n inappropriate in light of that.\n \n § Notes to the maintainer[1]\n \n This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:\n patch-id: fix accidental literal blocks, 2025-09-29) merged into\n v2.50.0 (because that’s what the topic is based on).\n \n (is there a “reference” convention for mentioning a topic + commit?)\n \n † 1: Inspired by\n • \n • SubmittingPatches: guidance for topic names and multi-series efforts\n • \n \n This is part one of a multi-series effort focusing on this\n documentation page. Technically that intent started with topic\n kh/doc-patch-id-markup-fix, but I published that before I learned\n about the idea presented in .\n So this gets named “part one” in the cover letter (and maybe on the\n topic name).\n \n The current plan for parts 2–5:\n \n 2. Various smaller fixups (many small patches/commits)\n 3. Mention the two config variables in git-config(1)\n 4. Make it more clear that you can feed multiple diffs to this command\n 5. An “Examples” section\n \n Why a multi-part series? It started with the idea of (1) emphasizing\n that this command can take multiple patches, and (2) making an\n Examples. But then I saw other things to fix. And they ought to go\n first... eventually I ended up with many commits or ideas.\n \n I wanted to see if this was easier to review.\n \n • Focus on uncontroversial changes first\n • Make all the series either small, simple/trivial, or both\n • Leave the changes that might spark discussion last; the ones that have\n to do with authoring new paragraphs/sections\n \n (I realize that multi-part series are probably mostly used for\n super-technical changes that take 50+ patches in total and that only\n three people on the list have the time and capacity to review at any\n given point in time.)\n\n Documentation/git-patch-id.adoc | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc\nindex 45da0f27acd..bfbf23f49c4 100644\n--- a/Documentation/git-patch-id.adoc\n+++ b/Documentation/git-patch-id.adoc\n@@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch\n \n SYNOPSIS\n --------\n-[verse]\n-'git patch-id' [--stable | --unstable | --verbatim]\n+[synopsis]\n+git patch-id [--stable | --unstable | --verbatim]\n \n DESCRIPTION\n -----------\n@@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same\n \n The main usecase for this command is to look for likely duplicate commits.\n \n-When dealing with 'git diff-tree' output, it takes advantage of\n+When dealing with `git diff-tree` output, it takes advantage of\n the fact that the patch is prefixed with the object name of the\n commit, and outputs two 40-byte hexadecimal strings. The first\n string is the patch ID, and the second string is the commit ID.\n@@ -30,19 +30,19 @@ This can be used to make a mapping from patch ID to commit ID.\n OPTIONS\n -------\n \n---verbatim::\n+`--verbatim`::\n \tCalculate the patch-id of the input as it is given, do not strip\n \tany whitespace.\n +\n This is the default if patchid.verbatim is true.\n \n---stable::\n+`--stable`::\n \tUse a \"stable\" sum of hashes as the patch ID. With this option:\n +\n --\n - Reordering file diffs that make up a patch does not affect the ID.\n In particular, two patches produced by comparing the same two trees\n- with two different settings for \"-O\" result in the same\n+ with two different settings for `-O` result in the same\n patch ID signature, thereby allowing the computed result to be used\n as a key to index some meta-information about the change between\n the two trees;\n@@ -50,7 +50,7 @@ This is the default if patchid.verbatim is true.\n - Result is different from the value produced by git 1.9 and older\n or produced when an \"unstable\" hash (see --unstable below) is\n configured - even when used on a diff output taken without any use\n- of \"-O\", thereby making existing databases storing such\n+ of `-O\", thereby making existing databases storing such\n \"unstable\" or historical patch-ids unusable.\n \n - All whitespace within the patch is ignored and does not affect the id.\n@@ -58,7 +58,7 @@ This is the default if patchid.verbatim is true.\n +\n This is the default if patchid.stable is set to true.\n \n---unstable::\n+`--unstable`::\n \tUse an \"unstable\" hash as the patch ID. With this option,\n \tthe result produced is compatible with the patch-id value produced\n \tby git 1.9 and older and whitespace is ignored. Users with pre-existing\n-- \n2.51.0.352.g356bc2d8d49\n\n"},{"id":"528452","messageId":"20251010050628.GB1897715@coredump.intra.peff.net","threadId":"64285","inReplyTo":"978261e3be4.1760043036.git.code@khaugsbakk.name","subject":"Re: [PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2025-10-10T05:06:28Z","receivedAt":"2025-10-10T05:06:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 09, 2025 at 10:53:53PM +0200, kristofferhaugsbakk@fastmail.com wrote:\n\n> Convert this command documentation to the modern synopsis style based on\n> similar work.[1] Concretely:\n> \n> • Change the Synopsis section from `verse` to a `synopsis` block which\n> will automatically apply the correct formatting to various elements\n> (although this Synopsis is very simple)\n> • Use backticks (`) for code-like things which will also use the correct\n> formatting for interior placeholders (``)\n> • Use backticks on options\n\nThese all look like strict improvements to me. Sadly doc-diff doesn't\nshow much here because the changes are mostly typographical, so I\neyeballed the HTML output (which does look much nicer).\n\n-Peff\n"},{"id":"528471","messageId":"d0dcaea3-844f-497a-adca-6241bf39db41@free.fr","threadId":"64285","inReplyTo":"978261e3be4.1760043036.git.code@khaugsbakk.name","subject":"Re: [PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-10-10T06:48:06Z","receivedAt":"2025-10-10T06:48:12Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 09/10/2025 à 22:53, kristofferhaugsbakk@fastmail.com a écrit :\n> From: Kristoffer Haugsbakk \n> \n> Convert this command documentation to the modern synopsis style based on\n> similar work.[1] Concretely:\n> \n> • Change the Synopsis section from `verse` to a `synopsis` block which\n> will automatically apply the correct formatting to various elements\n> (although this Synopsis is very simple)\n> • Use backticks (`) for code-like things which will also use the correct\n> formatting for interior placeholders (``)\n> • Use backticks on options\n> \n> † 1: E.g.,\n> • 026f2e3b (doc: convert git-log to new documentation format,\n> 2025-07-07)\n> • b983aaab (doc: convert git-switch manpage to new synopsis style,\n> 2025-05-25)\n> • 16543967 (doc: convert git-mergetool manpage to new synopsis\n> style, 2025-05-25)\n> \n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> \n> Notes (series):\n> Topic name: kh/patch-id-doc-part-one\n> \n> Topic summary: The documentation for \"git patch-id\" has been converted\n> to the modern \"synopsis\" style.\n> \n> Update git-patch-id(1) to the new synopsis style. This is done based on\n> observing what Jean-Noël Avila has done on other documentation pages.\n> \n> I don’t know what high-level plans Jean-Noël and the maintainer have for\n> the rewrite so I don’t know if posting this update is somehow\n> inappropriate in light of that.\n> \n> § Notes to the maintainer[1]\n> \n> This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:\n> patch-id: fix accidental literal blocks, 2025-09-29) merged into\n> v2.50.0 (because that’s what the topic is based on).\n> \n> (is there a “reference” convention for mentioning a topic + commit?)\n> \n> † 1: Inspired by\n> • \n> • SubmittingPatches: guidance for topic names and multi-series efforts\n> • \n> \n> This is part one of a multi-series effort focusing on this\n> documentation page. Technically that intent started with topic\n> kh/doc-patch-id-markup-fix, but I published that before I learned\n> about the idea presented in .\n> So this gets named “part one” in the cover letter (and maybe on the\n> topic name).\n> \n> The current plan for parts 2–5:\n> \n> 2. Various smaller fixups (many small patches/commits)\n> 3. Mention the two config variables in git-config(1)\n> 4. Make it more clear that you can feed multiple diffs to this command\n> 5. An “Examples” section\n> \n> Why a multi-part series? It started with the idea of (1) emphasizing\n> that this command can take multiple patches, and (2) making an\n> Examples. But then I saw other things to fix. And they ought to go\n> first... eventually I ended up with many commits or ideas.\n> \n> I wanted to see if this was easier to review.\n> \n> • Focus on uncontroversial changes first\n> • Make all the series either small, simple/trivial, or both\n> • Leave the changes that might spark discussion last; the ones that have\n> to do with authoring new paragraphs/sections\n> \n> (I realize that multi-part series are probably mostly used for\n> super-technical changes that take 50+ patches in total and that only\n> three people on the list have the time and capacity to review at any\n> given point in time.)\n> \n> Documentation/git-patch-id.adoc | 16 ++++++++--------\n> 1 file changed, 8 insertions(+), 8 deletions(-)\n> \n> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc\n> index 45da0f27acd..bfbf23f49c4 100644\n> --- a/Documentation/git-patch-id.adoc\n> +++ b/Documentation/git-patch-id.adoc\n> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch\n> \n> SYNOPSIS\n> --------\n> -[verse]\n> -'git patch-id' [--stable | --unstable | --verbatim]\n> +[synopsis]\n> +git patch-id [--stable | --unstable | --verbatim]\n> \n> DESCRIPTION\n> -----------\n> @@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same\n> \n> The main usecase for this command is to look for likely duplicate commits.\n> \n> -When dealing with 'git diff-tree' output, it takes advantage of\n> +When dealing with `git diff-tree` output, it takes advantage of\n> the fact that the patch is prefixed with the object name of the\n> commit, and outputs two 40-byte hexadecimal strings. The first\n> string is the patch ID, and the second string is the commit ID.\n> @@ -30,19 +30,19 @@ This can be used to make a mapping from patch ID to commit ID.\n> OPTIONS\n> -------\n> \n> ---verbatim::\n> +`--verbatim`::\n> \tCalculate the patch-id of the input as it is given, do not strip\n> \tany whitespace.\n> +\n> This is the default if patchid.verbatim is true.\n\nWe also format config names so here `patchid.verbatim`\n\n> \n> ---stable::\n> +`--stable`::\n> \tUse a \"stable\" sum of hashes as the patch ID. With this option:\n> +\n> --\n> - Reordering file diffs that make up a patch does not affect the ID.\n> In particular, two patches produced by comparing the same two trees\n> - with two different settings for \"-O\" result in the same\n> + with two different settings for `-O` result in the same\n> patch ID signature, thereby allowing the computed result to be used\n> as a key to index some meta-information about the change between\n> the two trees;\n> @@ -50,7 +50,7 @@ This is the default if patchid.verbatim is true.\n> - Result is different from the value produced by git 1.9 and older\n> or produced when an \"unstable\" hash (see --unstable below) is\n\n\nhere also \"see `--unstable` below\"\n\n> configured - even when used on a diff output taken without any use\n> - of \"-O\", thereby making existing databases storing such\n> + of `-O\", thereby making existing databases storing such\n> \"unstable\" or historical patch-ids unusable.\n> \n> - All whitespace within the patch is ignored and does not affect the id.\n> @@ -58,7 +58,7 @@ This is the default if patchid.verbatim is true.\n> +\n> This is the default if patchid.stable is set to true.\n\n`patchid.stable`\n\n> \n> ---unstable::\n> +`--unstable`::\n> \tUse an \"unstable\" hash as the patch ID. With this option,\n> \tthe result produced is compatible with the patch-id value produced\n> \tby git 1.9 and older and whitespace is ignored. Users with pre-existing\n\nThanks for jumping in the synopsis squad bandwagon!\n"},{"id":"528475","messageId":"xmqqcy6vb0nw.fsf@gitster.g","threadId":"64285","inReplyTo":"978261e3be4.1760043036.git.code@khaugsbakk.name","subject":"Re: [PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-10T08:50:43Z","receivedAt":"2025-10-10T08:50:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:\n> patch-id: fix accidental literal blocks, 2025-09-29) merged into\n> v2.50.0 (because that’s what the topic is based on).\n> \n> (is there a “reference” convention for mentioning a topic + commit?)\n\nThe above is perfectly understandable.\n\n> This is part one of a multi-series effort focusing on this\n> documentation page. Technically that intent started with topic\n> kh/doc-patch-id-markup-fix, but I published that before I learned\n> about the idea presented in .\n> So this gets named “part one” in the cover letter (and maybe on the\n> topic name).\n> \n> The current plan for parts 2–5:\n> \n> 2. Various smaller fixups (many small patches/commits)\n> 3. Mention the two config variables in git-config(1)\n> 4. Make it more clear that you can feed multiple diffs to this command\n> 5. An “Examples” section\n\nQuite honestly, this smells like making a mountain out of a\nmolehill. 5-patch topic that focuses on improving a single\ndocumentation page is nothing unusual, but it is very unusual and\nawkward to handle for a topic that focuses on improving a single\ndocumentation page is spread across 5 separate topics, each building\non top of the previous one.\n\n> Why a multi-part series? It started with the idea of (1) emphasizing\n> that this command can take multiple patches, and (2) making an\n> Examples. But then I saw other things to fix. And they ought to go\n> first... eventually I ended up with many commits or ideas.\n\nPerhaps then after you built up the final shape, you'd need time to\nruminate over it and possibly reorganize to find the best order and\norganization to present it as a N-patch single series? Typically, a\ncollection of thoughts presented in the order they came to one's mind\nis much harder to judge, relative to an effort to tell a coherent story\nthat moves to a goal.\n\nBut we'll see.\n"},{"id":"528629","messageId":"c29d957e-7dd2-4bd4-9ce8-9caa56d1cbdf@app.fastmail.com","threadId":"64285","inReplyTo":"d0dcaea3-844f-497a-adca-6241bf39db41@free.fr","subject":"Re: [PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-13T14:54:14Z","receivedAt":"2025-10-13T14:54:37Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Oct 10, 2025, at 08:48, Jean-Noël Avila wrote:\n>[snip feedback]\n\nThank you. I’ve updated for v2.\n\n>\n>>\n>> ---unstable::\n>> +`--unstable`::\n>> \tUse an \"unstable\" hash as the patch ID. With this option,\n>> \tthe result produced is compatible with the patch-id value produced\n>> \tby git 1.9 and older and whitespace is ignored. Users with pre-existing\n>\n> Thanks for jumping in the synopsis squad bandwagon!\n\n:)\n"},{"id":"528630","messageId":"932d3fd8-7fd3-4d1c-b3a7-644fb04ef47d@app.fastmail.com","threadId":"64285","inReplyTo":"20251010050628.GB1897715@coredump.intra.peff.net","subject":"Re: [PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-10-13T15:03:43Z","receivedAt":"2025-10-13T15:04:05Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Fri, Oct 10, 2025, at 07:06, Jeff King wrote:\n> On Thu, Oct 09, 2025 at 10:53:53PM +0200,\n> kristofferhaugsbakk@fastmail.com wrote:\n>\n>> Convert this command documentation to the modern synopsis style based on\n>> similar work.[1] Concretely:\n>>\n>> • Change the Synopsis section from `verse` to a `synopsis` block which\n>> will automatically apply the correct formatting to various elements\n>> (although this Synopsis is very simple)\n>> • Use backticks (`) for code-like things which will also use the correct\n>> formatting for interior placeholders (``)\n>> • Use backticks on options\n>\n> These all look like strict improvements to me. Sadly doc-diff doesn't\n> show much here because the changes are mostly typographical, so I\n> eyeballed the HTML output (which does look much nicer).\n\nThanks for testing!\n\n-- \nKristoffer\n\n"},{"id":"528636","messageId":"v2-38645ea253c.1760369708.git.code@khaugsbakk.name","threadId":"64285","inReplyTo":"978261e3be4.1760043036.git.code@khaugsbakk.name","subject":"[PATCH v2] doc: patch-id: convert to the modern synopsis style","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-13T15:42:15Z","receivedAt":"2025-10-13T15:42:30Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nConvert this command documentation to the modern synopsis style based on\nsimilar work.[1] Concretely:\n\n• Change the Synopsis section from `verse` to a `synopsis` block which\n will automatically apply the correct formatting to various elements\n (although this Synopsis is very simple)\n• Use backticks (`) for code-like things which will also use the correct\n formatting for interior placeholders (``)\n• Use inline-verbatim on options listing\n\n† 1: E.g.,\n • 026f2e3b (doc: convert git-log to new documentation format,\n 2025-07-07)\n • b983aaab (doc: convert git-switch manpage to new synopsis style,\n 2025-05-25)\n • 16543967 (doc: convert git-mergetool manpage to new synopsis\n style, 2025-05-25)\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n Topic name (applied): kh/doc-patch-id-1\n \n Topic summary: The documentation for \"git patch-id\" has been converted\n to the modern \"synopsis\" style.\n \n Update git-patch-id(1) to the new synopsis style. This is done based on\n observing what Jean-Noël Avila has done on other documentation pages.\n \n I don’t know what high-level plans Jean-Noël and the maintainer have for\n the rewrite so I don’t know if posting this update is somehow\n inappropriate in light of that.\n \n § Changes in v2\n \n Add more inline-verbatim (`) based on feedback from Jean-Noël. Details:\n \n • More inline-verbatim markup\n • From feedback\n • Also: on config value (`true`)\n • Tweak commit message; refer to “options listing” for the left-flushed\n options to distinguish from running text\n • Fix mistake from v1 in markup for `-O`\n \n § Notes to the maintainer[1] (unchanged in v2)\n \n This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:\n patch-id: fix accidental literal blocks, 2025-09-29) merged into\n v2.50.0 (because that’s what the topic is based on).\n \n (is there a “reference” convention for mentioning a topic + commit?)\n \n † 1: Inspired by\n • \n • SubmittingPatches: guidance for topic names and multi-series efforts\n • \n \n This is part one of a multi-series effort focusing on this\n documentation page. Technically that intent started with topic\n kh/doc-patch-id-markup-fix, but I published that before I learned\n about the idea presented in .\n So this gets named “part one” in the cover letter (and maybe on the\n topic name).\n \n The current plan for parts 2–5:\n \n 2. Various smaller fixups (many small patches/commits)\n 3. Mention the two config variables in git-config(1)\n 4. Make it more clear that you can feed multiple diffs to this command\n 5. An “Examples” section\n \n Why a multi-part series? It started with the idea of (1) emphasizing\n that this command can take multiple patches, and (2) making an\n Examples. But then I saw other things to fix. And they ought to go\n first... eventually I ended up with many commits or ideas.\n \n I wanted to see if this was easier to review.\n \n • Focus on uncontroversial changes first\n • Make all the series either small, simple/trivial, or both\n • Leave the changes that might spark discussion last; the ones that have\n to do with authoring new paragraphs/sections\n \n (I realize that multi-part series are probably mostly used for\n super-technical changes that take 50+ patches in total and that only\n three people on the list have the time and capacity to review at any\n given point in time.)\n\n Documentation/git-patch-id.adoc | 22 +++++++++++-----------\n 1 file changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc\nindex 45da0f27acd..92a1af36a27 100644\n--- a/Documentation/git-patch-id.adoc\n+++ b/Documentation/git-patch-id.adoc\n@@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch\n \n SYNOPSIS\n --------\n-[verse]\n-'git patch-id' [--stable | --unstable | --verbatim]\n+[synopsis]\n+git patch-id [--stable | --unstable | --verbatim]\n \n DESCRIPTION\n -----------\n@@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same\n \n The main usecase for this command is to look for likely duplicate commits.\n \n-When dealing with 'git diff-tree' output, it takes advantage of\n+When dealing with `git diff-tree` output, it takes advantage of\n the fact that the patch is prefixed with the object name of the\n commit, and outputs two 40-byte hexadecimal strings. The first\n string is the patch ID, and the second string is the commit ID.\n@@ -30,35 +30,35 @@ This can be used to make a mapping from patch ID to commit ID.\n OPTIONS\n -------\n \n---verbatim::\n+`--verbatim`::\n \tCalculate the patch-id of the input as it is given, do not strip\n \tany whitespace.\n +\n-This is the default if patchid.verbatim is true.\n+This is the default if `patchid.verbatim` is `true`.\n \n---stable::\n+`--stable`::\n \tUse a \"stable\" sum of hashes as the patch ID. With this option:\n +\n --\n - Reordering file diffs that make up a patch does not affect the ID.\n In particular, two patches produced by comparing the same two trees\n- with two different settings for \"-O\" result in the same\n+ with two different settings for `-O` result in the same\n patch ID signature, thereby allowing the computed result to be used\n as a key to index some meta-information about the change between\n the two trees;\n \n - Result is different from the value produced by git 1.9 and older\n- or produced when an \"unstable\" hash (see --unstable below) is\n+ or produced when an \"unstable\" hash (see `--unstable` below) is\n configured - even when used on a diff output taken without any use\n- of \"-O\", thereby making existing databases storing such\n+ of `-O`, thereby making existing databases storing such\n \"unstable\" or historical patch-ids unusable.\n \n - All whitespace within the patch is ignored and does not affect the id.\n --\n +\n-This is the default if patchid.stable is set to true.\n+This is the default if `patchid.stable` is set to `true`.\n \n---unstable::\n+`--unstable`::\n \tUse an \"unstable\" hash as the patch ID. With this option,\n \tthe result produced is compatible with the patch-id value produced\n \tby git 1.9 and older and whitespace is ignored. Users with pre-existing\n\nInterdiff against v1:\n diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc\n index bfbf23f49c4..92a1af36a27 100644\n --- a/Documentation/git-patch-id.adoc\n +++ b/Documentation/git-patch-id.adoc\n @@ -34,7 +34,7 @@ OPTIONS\n \tCalculate the patch-id of the input as it is given, do not strip\n \tany whitespace.\n +\n -This is the default if patchid.verbatim is true.\n +This is the default if `patchid.verbatim` is `true`.\n \n `--stable`::\n \tUse a \"stable\" sum of hashes as the patch ID. With this option:\n @@ -48,15 +48,15 @@ This is the default if patchid.verbatim is true.\n the two trees;\n \n - Result is different from the value produced by git 1.9 and older\n - or produced when an \"unstable\" hash (see --unstable below) is\n + or produced when an \"unstable\" hash (see `--unstable` below) is\n configured - even when used on a diff output taken without any use\n - of `-O\", thereby making existing databases storing such\n + of `-O`, thereby making existing databases storing such\n \"unstable\" or historical patch-ids unusable.\n \n - All whitespace within the patch is ignored and does not affect the id.\n --\n +\n -This is the default if patchid.stable is set to true.\n +This is the default if `patchid.stable` is set to `true`.\n \n `--unstable`::\n \tUse an \"unstable\" hash as the patch ID. With this option,\n\nRange-diff against v1:\n1: 978261e3be4 ! 1: 38645ea253c doc: patch-id: convert to the modern synopsis style\n @@ Commit message\n (although this Synopsis is very simple)\n • Use backticks (`) for code-like things which will also use the correct\n formatting for interior placeholders (``)\n - • Use backticks on options\n + • Use inline-verbatim on options listing\n \n † 1: E.g.,\n • 026f2e3b (doc: convert git-log to new documentation format,\n @@ Commit message\n \n \n ## Notes (series) ##\n - Topic name: kh/patch-id-doc-part-one\n + Topic name (applied): kh/doc-patch-id-1\n \n Topic summary: The documentation for \"git patch-id\" has been converted\n to the modern \"synopsis\" style.\n @@ Notes (series)\n the rewrite so I don’t know if posting this update is somehow\n inappropriate in light of that.\n \n - § Notes to the maintainer[1]\n + § Changes in v2\n +\n + Add more inline-verbatim (`) based on feedback from Jean-Noël. Details:\n +\n + • More inline-verbatim markup\n + • From feedback\n + • Also: on config value (`true`)\n + • Tweak commit message; refer to “options listing” for the left-flushed\n + options to distinguish from running text\n + • Fix mistake from v1 in markup for `-O`\n +\n + § Notes to the maintainer[1] (unchanged in v2)\n \n This depends on the topic kh/doc-patch-id-markup-fix (39969438 (doc:\n patch-id: fix accidental literal blocks, 2025-09-29) merged into\n @@ Documentation/git-patch-id.adoc: This can be used to make a mapping from patch I\n \tCalculate the patch-id of the input as it is given, do not strip\n \tany whitespace.\n +\n - This is the default if patchid.verbatim is true.\n +-This is the default if patchid.verbatim is true.\n ++This is the default if `patchid.verbatim` is `true`.\n \n ---stable::\n +`--stable`::\n @@ Documentation/git-patch-id.adoc: This can be used to make a mapping from patch I\n patch ID signature, thereby allowing the computed result to be used\n as a key to index some meta-information about the change between\n the two trees;\n -@@ Documentation/git-patch-id.adoc: This is the default if patchid.verbatim is true.\n + \n - Result is different from the value produced by git 1.9 and older\n - or produced when an \"unstable\" hash (see --unstable below) is\n +- or produced when an \"unstable\" hash (see --unstable below) is\n ++ or produced when an \"unstable\" hash (see `--unstable` below) is\n configured - even when used on a diff output taken without any use\n - of \"-O\", thereby making existing databases storing such\n -+ of `-O\", thereby making existing databases storing such\n ++ of `-O`, thereby making existing databases storing such\n \"unstable\" or historical patch-ids unusable.\n \n - All whitespace within the patch is ignored and does not affect the id.\n -@@ Documentation/git-patch-id.adoc: This is the default if patchid.verbatim is true.\n + --\n +\n - This is the default if patchid.stable is set to true.\n +-This is the default if patchid.stable is set to true.\n ++This is the default if `patchid.stable` is set to `true`.\n \n ---unstable::\n +`--unstable`::\n-- \n2.51.0.352.g356bc2d8d49\n\n"},{"id":"528640","messageId":"ccbaa98e-7223-4c75-9844-f0025de9f84c@app.fastmail.com","threadId":"64285","inReplyTo":"xmqqcy6vb0nw.fsf@gitster.g","subject":"Re: [PATCH] doc: patch-id: convert to the modern synopsis style","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-10-13T16:42:28Z","receivedAt":"2025-10-13T16:42:50Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Fri, Oct 10, 2025, at 10:50, Junio C Hamano wrote:\n>> This is part one of a multi-series effort focusing on this\n>> documentation page. Technically that intent started with topic\n>> kh/doc-patch-id-markup-fix, but I published that before I learned\n>> about the idea presented in .\n>> So this gets named “part one” in the cover letter (and maybe on the\n>> topic name).\n>>\n>> The current plan for parts 2–5:\n>>\n>> 2. Various smaller fixups (many small patches/commits)\n>> 3. Mention the two config variables in git-config(1)\n>> 4. Make it more clear that you can feed multiple diffs to this command\n>> 5. An “Examples” section\n>\n> Quite honestly, this smells like making a mountain out of a\n> molehill.\n\nGot it.\n\n> 5-patch topic that focuses on improving a single\n> documentation page is nothing unusual, but it is very unusual and\n> awkward to handle for a topic that focuses on improving a single\n> documentation page is spread across 5 separate topics, each building\n> on top of the previous one.\n\nTo be sure: I’ll abort the plan if it turns out to be worse for the\nreviewers.\n\nI can make the following amemdment right now: after this current topic I\nwill wait until it graduates to `master` instead of basing the next\ntopic on the merge to `next`.\n\nEither that or everything that I plan to send gets sent in the next\ntopic.\n\n>\n>> Why a multi-part series? It started with the idea of (1) emphasizing\n>> that this command can take multiple patches, and (2) making an\n>> Examples. But then I saw other things to fix. And they ought to go\n>> first... eventually I ended up with many commits or ideas.\n>\n> Perhaps then after you built up the final shape, you'd need time to\n> ruminate over it and possibly reorganize to find the best order and\n> organization to present it as a N-patch single series? Typically, a\n> collection of thoughts presented in the order they came to one's mind\n> is much harder to judge, relative to an effort to tell a coherent story\n> that moves to a goal.\n\nThat’s a good point. I will rather scrap things and recreate them if I\ncome up with a better order rather than committing to the existing one.\n"},{"id":"528642","messageId":"CAPig+cSQB0HbhY2L1Y4mkbaCMiZTH72AtQ+qRg=Z0U9_ggkcug@mail.gmail.com","threadId":"64285","inReplyTo":"v2-38645ea253c.1760369708.git.code@khaugsbakk.name","subject":"Re: [PATCH v2] doc: patch-id: convert to the modern synopsis style","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-10-13T16:53:36Z","receivedAt":"2025-10-13T16:53:48Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Oct 13, 2025 at 12:28 PM wrote:\n> Convert this command documentation to the modern synopsis style based on\n> similar work.[1] Concretely: [...]\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc\n> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch\n> ---unstable::\n> +`--unstable`::\n> Use an \"unstable\" hash as the patch ID. With this option,\n> the result produced is compatible with the patch-id value produced\n> by git 1.9 and older and whitespace is ignored. Users with pre-existing\n\nIs the mix of \"patch ID\" and \"patch-id\" intentional? If so, should\n\"patch-id\" be wrapped in backticks?\n"},{"id":"528763","messageId":"c9314e08-e0eb-4de4-8f34-a6b4de69e28f@app.fastmail.com","threadId":"64285","inReplyTo":"CAPig+cSQB0HbhY2L1Y4mkbaCMiZTH72AtQ+qRg=Z0U9_ggkcug@mail.gmail.com","subject":"Re: [PATCH v2] doc: patch-id: convert to the modern synopsis style","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-10-14T20:46:48Z","receivedAt":"2025-10-14T20:47:09Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Mon, Oct 13, 2025, at 18:53, Eric Sunshine wrote:\n> On Mon, Oct 13, 2025 at 12:28 PM wrote:\n>> Convert this command documentation to the modern synopsis style based on\n>> similar work.[1] Concretely: [...]\n>>\n>> Signed-off-by: Kristoffer Haugsbakk \n>> ---\n>> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc\n>> @@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch\n>> ---unstable::\n>> +`--unstable`::\n>> Use an \"unstable\" hash as the patch ID. With this option,\n>> the result produced is compatible with the patch-id value produced\n>> by git 1.9 and older and whitespace is ignored. Users with pre-existing\n>\n> Is the mix of \"patch ID\" and \"patch-id\" intentional? If so, should\n> \"patch-id\" be wrapped in backticks?\n\nI originally assumed that “patch-id” here meant “patch ID` but now I’m\nnot sure (what was intended).\n\nThe way I read it then made me change all of these “patch-id” to “patch\nID” for consistency. That’s a future change/topic.\n"}]}