[PATCH v2 0/3] doc: patch-id: explain how to map efficiently

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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/c70adde6-e3db-4a46-bb29-a19d7aba8c7e@app.fastmail.com/

§ Previous patch series

• Patch series 1:
  • Topic: kh/doc-patch-id-markup-fix
  • https://lore.kernel.org/git/v2-e5ad12cc3b3.1759178715.git.code@khaugsbakk.name/
• Patch series 2:
  • Topic: kh/doc-patch-id-1
  • https://lore.kernel.org/git/v2-38645ea253c.1760369708.git.code@khaugsbakk.name/
• Patch series 3:
  • Topic: kh/doc-patch-id
  • https://lore.kernel.org/git/CV_doc_patch-id_3.1ab@msgid.xyz/

Link to v1: https://lore.kernel.org/git/CV_doc_patch-id_4.275@msgid.xyz/#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:
diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index fb9ec211bb6..05859990c8e 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -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
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
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/
     
         Inspired-by: Linus Torvalds <torvalds@linux-foundation.org>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    @@ 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
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## 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