doc: patch-id: explain how to map efficiently

From: Kristoffer Haugsbakk <[email protected]>

Topic name (applied): kh/doc-patch-id-4

Topic summary: Explain and emphasize how to map commits efficiently and add an example script.

This is the fourth patch series for git-patch-id(1). This one focuses on emphasizing how the command is an efficient patch ID–commit mapper and how to use the patch IDs to join commits in a script.

§ Changes in v2

• Delete temporary files at the end of the script.
• Consistent footnote style: https://lore.kernel.org/git/[email protected]/

§ Previous patch series

• Patch series 1:
• Topic: kh/doc-patch-id-markup-fix
• https://lore.kernel.org/git/[email protected]/
• Patch series 2:
• Topic: kh/doc-patch-id-1
• https://lore.kernel.org/git/[email protected]/
• Patch series 3:
• Topic: kh/doc-patch-id
• https://lore.kernel.org/git/[email protected]/

Link to v1: https://lore.kernel.org/git/[email protected]/#t

Kristoffer Haugsbakk (3):
doc: patch-id: emphasize multi-patch processing
doc: patch-id: add script example
doc: patch-id: see also git-cherry(1)

 Documentation/git-patch-id.adoc | 51 +++++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 3 deletions(-)

Interdiff against v1:

index fb9ec211bb6..05859990c8e 100644
@@ -101,6 +101,8 @@ git rev-list --no-merges $tail_opts |
     git diff-tree --patch --stdin |
     git patch-id  --stable | sort >"$for_upstream"
 join -a1 "$for_branch" "$for_upstream" | cut -d' ' -f2,3
+rm "$for_branch"
+rm "$for_upstream"
 ----
 
 Now the first column shows the commit from your branch and the second

Range-diff against v1:
1: 704dc0ada8f ! 1: e9319039d5e doc: patch-id: emphasize multi-patch processing
@@ Commit message

Also drop “the” from “standard input”.

- [1]: https://stackoverflow.com/a/19758159
+ † 1: https://stackoverflow.com/a/19758159
† 2: This is master of this repository on 2025-10-02

2: e37c25aa5fc ! 2: 8ba3e71752c doc: patch-id: add script example
@@ Commit message
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/
+ † 1: https://lore.kernel.org/workflows/CAHk-=wiN+8EUoik4UeAJ-HPSU7hczQP+8+_uP3vtAy_=YfJ9PQ@mail.gmail.com/

@@ Documentation/git-patch-id.adoc: This is the default if patchid.stable is set
+ git diff-tree --patch --stdin |
+ git patch-id --stable | sort >"$for_upstream"
+join -a1 "$for_branch" "$for_upstream" | cut -d' ' -f2,3
++rm "$for_branch"
++rm "$for_upstream"
+----
+
+Now the first column shows the commit from your branch and the second
3: 2a319a43b2e ! 3: 27cad849312 doc: patch-id: see also git-cherry(1)
@@ Commit message

## Documentation/git-patch-id.adoc ##
-@@ Documentation/git-patch-id.adoc: join -a1 "$for_branch" "$for_upstream" | cut -d' ' -f2,3 +@@ Documentation/git-patch-id.adoc: rm "$for_upstream"
Now the first column shows the commit from your branch and the second column shows the patch ID equivalent commit, if it exists.

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f

2.53.0.26.g2afa8602a26