git/Documentation/git-patch-id.adoc, branch jch

doc: patch-id: see also git-cherry(1)

2026-02-17T18:49:51Z

git-cherry(1) links to this command. These two commands are similar and we also mention it in the “Examples” section now. Let’s link to it. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: add script example

2026-02-17T18:49:51Z

The utility and usability of git-patch-id(1) was discussed relatively recently:[1] Using "git patch-id" is definitely in the "write a script for it" category. I don't think I've ever used it as-is from the command line as part of a one-liner. It's very much a command that is designed purely for scripting, the interface is just odd and baroque and doesn't really make sense for one-liners. The typical use of patch-id is to generate two *lists* of patch-ids, then sort them and use the patch-id as a key to find commits that look the same. The command doc *could* use an example, and since it is a mapper command it makes sense for that example to be a little script. Mapping the commits of some branch to an upstream ref allows us to demonstrate generating two lists, sorting them, joining them, and finally discarding the patch ID lookup column with cut(1). † 1: https://lore.kernel.org/workflows/CAHk-=wiN+8EUoik4UeAJ-HPSU7hczQP+8+_uP3vtAy_=YfJ9PQ@mail.gmail.com/ Inspired-by: Linus Torvalds Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: emphasize multi-patch processing

2026-02-17T18:49:51Z

Emphasize that you can pass multiple patches or diffs to this command. git-patch-id(1) is an efficient pID–commit mapper, able to map thousands of commits in seconds. But discussions on the command seem to typically[1] use the standard loop-over-rev-list-and- shell-out pattern: for commit in rev-list: prepare a diff from commit | git patch-id This is unnecessary; we can bulk-process the patches: git rev-list --no-merges | git diff-tree --patch --stdin | git patch-id --stable The first version (translated to shell) takes a little over nine minutes for a commit history of about 78K commits.[2] The other one, by contrast, takes slightly less than a minute. Also drop “the” from “standard input”. † 1: https://stackoverflow.com/a/19758159 † 2: This is `master` of this repository on 2025-10-02 Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: --verbatim locks in --stable

2026-01-09T14:08:37Z

The default `--unstable` is a legacy format that predates `--stable`. That’s why 2871f4d4 (builtin: patch-id: add --verbatim as a command mode, 2022-10-24) made `--verbatim` lock in[1] `--stable`: Users of --unstable mainly care about compatibility with old git versions, which unstripping the whitespace would break. Thus there isn't a usecase for the combination of --verbatim and --unstable, and we don't expose this so as to not add maintainence burden. † 1: imply `--stable`, disallow `--unstable` Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: spell out the git-diff-tree(1) form

2026-01-09T14:07:22Z

You specifically need `--patch` since the default output is a raw diff. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: use definite article for the result

2026-01-09T14:07:21Z

Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

patch-id: use “patch ID” throughout

2026-01-09T14:07:21Z

The “Description” section decided to introduce and use the term “patch ID” for the ID value itself. Let’s use the same term on the options as well. Also make to sure to use bare “ID” instead of “id”. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: capitalize Git version

2026-01-09T14:07:21Z

Git versions are always capitalized. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: don’t use semicolon between bullet points

2026-01-09T14:07:20Z

These bullet points are full-fledged paragraphs with sentences. It’s best to restrict semicolon-termination to the case when the bullet list amounts to a list of items.[1] † 1: Like “List: ... • first; ... • second; and ... • third.” Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: patch-id: convert to the modern synopsis style

2025-10-13T15:53:13Z

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 (``) • 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 Signed-off-by: Junio C Hamano