threads / patch / 64938

patch, 3 partsdoc: patch-id: explain how to map efficiently

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

## tl;dr

15 messages between Feb 7, 2026 and Feb 23, 2026. Diffs are folded; open one to read it.

replies: 14people: 4as markdown or json

kristofferhaugsbakk@fastmail.com· Feb 7, 2026, 15:05 UTC · lore

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name: 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.

• 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/

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 | 49 +++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 3 deletions(-)

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f

-- 
2.53.0.26.g2afa8602a26

kristofferhaugsbakk@fastmail.com· Feb 7, 2026, 15:05 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 1/3] doc: patch-id: emphasize multi-patch processing

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <ref> |
         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 <code@khaugsbakk.name>
---
 Documentation/git-patch-id.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

Show changes to Documentation/git-patch-id.adoc +4 −3

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index 013e1a61906..e95391cd255 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -3,7 +3,7 @@ git-patch-id(1)
 
 NAME
 ----
-git-patch-id - Compute unique ID for a patch
+git-patch-id - Compute unique IDs for patches
 
 SYNOPSIS
 --------
@@ -12,7 +12,7 @@ git patch-id [--stable | --unstable | --verbatim]
 
 DESCRIPTION
 -----------
-Read a patch from the standard input and compute the patch ID for it.
+Read patches from standard input and compute the patch IDs.
 
 A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a
 patch, with line numbers ignored.  As such, it's "reasonably stable", but at
@@ -25,7 +25,8 @@ When dealing with `git diff-tree --patch` 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.
-This can be used to make a mapping from patch ID to commit ID.
+This can be used to make a mapping from patch ID to commit ID for a
+set or range of commits.
 
 OPTIONS
 -------

-- 
2.53.0.26.g2afa8602a26

kristofferhaugsbakk@fastmail.com· Feb 7, 2026, 15:05 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 2/3] doc: patch-id: add script example

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <torvalds@linux-foundation.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    The script will not list the commits in rev-list order because of
    the sorting.

 Documentation/git-patch-id.adoc | 38 +++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

Show changes to Documentation/git-patch-id.adoc +38 −0

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index e95391cd255..19780f86425 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -68,6 +68,44 @@ This is the default if `patchid.stable` is set to `true`.
 +
 This is the default.
 
+EXAMPLES
+--------
+
+linkgit:git-cherry[1] shows what commits from a branch have patch ID
+equivalent commits in some upstream branch. But it only tells you
+whether such a commit exists or not. What if you wanted to know the
+relevant commits in the upstream? We can use this command to make a
+mapping between your branch and the upstream branch:
+
+----
+#!/bin/sh
+
+upstream="$1"
+branch="$2"
+test -z "$branch" && branch=HEAD
+limit="$3"
+if test -n "$limit"
+then
+    tail_opts="$limit".."$upstream"
+else
+    since=$(git log --format=%aI "$upstream".."$branch" | tail -1)
+    tail_opts=--since="$since"' '"$upstream"
+fi
+for_branch=$(mktemp)
+for_upstream=$(mktemp)
+
+git rev-list --no-merges "$upstream".."$branch" |
+    git diff-tree --patch --stdin |
+    git patch-id  --stable | sort >"$for_branch"
+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
+----
+
+Now the first column shows the commit from your branch and the second
+column shows the patch ID equivalent commit, if it exists.
+
 GIT
 ---
 Part of the linkgit:git[1] suite

-- 
2.53.0.26.g2afa8602a26

D. Ben Knoble· Feb 8, 2026, 02:34 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 2/3] doc: patch-id: add script example

On Sat, Feb 7, 2026 at 10:07 AM <kristofferhaugsbakk@fastmail.com> wrote:

Show 69 quoted lines

>
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 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 <torvalds@linux-foundation.org>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>
> Notes (series):
>     The script will not list the commits in rev-list order because of
>     the sorting.
>
>  Documentation/git-patch-id.adoc | 38 +++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>
> diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
> index e95391cd255..19780f86425 100644
> --- a/Documentation/git-patch-id.adoc
> +++ b/Documentation/git-patch-id.adoc
> @@ -68,6 +68,44 @@ This is the default if `patchid.stable` is set to `true`.
>  +
>  This is the default.
>
> +EXAMPLES
> +--------
> +
> +linkgit:git-cherry[1] shows what commits from a branch have patch ID
> +equivalent commits in some upstream branch. But it only tells you
> +whether such a commit exists or not. What if you wanted to know the
> +relevant commits in the upstream? We can use this command to make a
> +mapping between your branch and the upstream branch:
> +
> +----
> +#!/bin/sh
> +
> +upstream="$1"
> +branch="$2"
> +test -z "$branch" && branch=HEAD
> +limit="$3"
> +if test -n "$limit"
> +then
> +    tail_opts="$limit".."$upstream"
> +else
> +    since=$(git log --format=%aI "$upstream".."$branch" | tail -1)
> +    tail_opts=--since="$since"' '"$upstream"
> +fi
> +for_branch=$(mktemp)
> +for_upstream=$(mktemp)

Do we want to delete these when we are done (via trap or just cleanup at the end)?

Show 20 quoted lines

> +
> +git rev-list --no-merges "$upstream".."$branch" |
> +    git diff-tree --patch --stdin |
> +    git patch-id  --stable | sort >"$for_branch"
> +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
> +----
> +
> +Now the first column shows the commit from your branch and the second
> +column shows the patch ID equivalent commit, if it exists.
> +
>  GIT
>  ---
>  Part of the linkgit:git[1] suite
> --
> 2.53.0.26.g2afa8602a26
>
>

-- 
D. Ben Knoble

Kristoffer Haugsbakk· Feb 8, 2026, 17:23 UTC · re: D. Ben Knoble · lore

Re: [PATCH 2/3] doc: patch-id: add script example

On Sun, Feb 8, 2026, at 03:34, D. Ben Knoble wrote:

Show 19 quoted lines

>>[snip]
>> +#!/bin/sh
>> +
>> +upstream="$1"
>> +branch="$2"
>> +test -z "$branch" && branch=HEAD
>> +limit="$3"
>> +if test -n "$limit"
>> +then
>> +    tail_opts="$limit".."$upstream"
>> +else
>> +    since=$(git log --format=%aI "$upstream".."$branch" | tail -1)
>> +    tail_opts=--since="$since"' '"$upstream"
>> +fi
>> +for_branch=$(mktemp)
>> +for_upstream=$(mktemp)
>
> Do we want to delete these when we are done (via trap or just cleanup
> at the end)?

Sounds good. Maybe just at the end since this is a happy-path example script. ;) (not very robust and all that)

>
>[snip]

kristofferhaugsbakk@fastmail.com· Feb 7, 2026, 15:05 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 3/3] doc: patch-id: see also git-cherry(1)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---
 Documentation/git-patch-id.adoc | 4 ++++
 1 file changed, 4 insertions(+)

Show changes to Documentation/git-patch-id.adoc +4 −0

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index 19780f86425..fb9ec211bb6 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -106,6 +106,10 @@ join -a1 "$for_branch" "$for_upstream" | cut -d' ' -f2,3
 Now the first column shows the commit from your branch and the second
 column shows the patch ID equivalent commit, if it exists.
 
+SEE ALSO
+--------
+linkgit:git-cherry[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite

-- 
2.53.0.26.g2afa8602a26

D. Ben Knoble· Feb 8, 2026, 02:34 UTC · re: kristofferhaugsbakk@fastmail.com · lore

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

On Sat, Feb 7, 2026 at 10:06 AM <kristofferhaugsbakk@fastmail.com> wrote:

Show 34 quoted lines

>
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Topic name: 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.
>
> • 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/
>
> 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 | 49 +++++++++++++++++++++++++++++++--
>  1 file changed, 46 insertions(+), 3 deletions(-)
>
>
> base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
> --
> 2.53.0.26.g2afa8602a26

Short and sweet with a nice demo of how to use git-patch-id(1). One nit on the script, but otherwise LGTM.

-- D. Ben Knoble

kristofferhaugsbakk@fastmail.com· Feb 14, 2026, 11:55 UTC · re: kristofferhaugsbakk@fastmail.com · lore

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

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:

Show changes to Documentation/git-patch-id.adoc +2 −0

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

kristofferhaugsbakk@fastmail.com· Feb 14, 2026, 11:55 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 1/3] doc: patch-id: emphasize multi-patch processing

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Emphasize that you can pass multiple patches or diffs to this command.

    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 <ref> |
         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 <code@khaugsbakk.name>
---

Notes (series):
    v2: Use my weird daggers consistently for footnotes

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

Show changes to Documentation/git-patch-id.adoc +4 −3

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index 013e1a61906..e95391cd255 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -3,7 +3,7 @@ git-patch-id(1)
 
 NAME
 ----
-git-patch-id - Compute unique ID for a patch
+git-patch-id - Compute unique IDs for patches
 
 SYNOPSIS
 --------
@@ -12,7 +12,7 @@ git patch-id [--stable | --unstable | --verbatim]
 
 DESCRIPTION
 -----------
-Read a patch from the standard input and compute the patch ID for it.
+Read patches from standard input and compute the patch IDs.
 
 A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a
 patch, with line numbers ignored.  As such, it's "reasonably stable", but at
@@ -25,7 +25,8 @@ When dealing with `git diff-tree --patch` 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.
-This can be used to make a mapping from patch ID to commit ID.
+This can be used to make a mapping from patch ID to commit ID for a
+set or range of commits.
 
 OPTIONS
 -------

-- 
2.53.0.26.g2afa8602a26

kristofferhaugsbakk@fastmail.com· Feb 14, 2026, 11:55 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 2/3] doc: patch-id: add script example

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <torvalds@linux-foundation.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Delete temporary files
    • Use my weird daggers consistently for footnotes
    v1:
    The script will not list the commits in rev-list order because of
    the sorting.

 Documentation/git-patch-id.adoc | 40 +++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

Show changes to Documentation/git-patch-id.adoc +40 −0

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index e95391cd255..1618994e76c 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -68,6 +68,46 @@ This is the default if `patchid.stable` is set to `true`.
 +
 This is the default.
 
+EXAMPLES
+--------
+
+linkgit:git-cherry[1] shows what commits from a branch have patch ID
+equivalent commits in some upstream branch. But it only tells you
+whether such a commit exists or not. What if you wanted to know the
+relevant commits in the upstream? We can use this command to make a
+mapping between your branch and the upstream branch:
+
+----
+#!/bin/sh
+
+upstream="$1"
+branch="$2"
+test -z "$branch" && branch=HEAD
+limit="$3"
+if test -n "$limit"
+then
+    tail_opts="$limit".."$upstream"
+else
+    since=$(git log --format=%aI "$upstream".."$branch" | tail -1)
+    tail_opts=--since="$since"' '"$upstream"
+fi
+for_branch=$(mktemp)
+for_upstream=$(mktemp)
+
+git rev-list --no-merges "$upstream".."$branch" |
+    git diff-tree --patch --stdin |
+    git patch-id  --stable | sort >"$for_branch"
+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
+column shows the patch ID equivalent commit, if it exists.
+
 GIT
 ---
 Part of the linkgit:git[1] suite

-- 
2.53.0.26.g2afa8602a26

kristofferhaugsbakk@fastmail.com· Feb 14, 2026, 11:55 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 3/3] doc: patch-id: see also git-cherry(1)

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---
 Documentation/git-patch-id.adoc | 4 ++++
 1 file changed, 4 insertions(+)

Show changes to Documentation/git-patch-id.adoc +4 −0

diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc
index 1618994e76c..05859990c8e 100644
--- a/Documentation/git-patch-id.adoc
+++ b/Documentation/git-patch-id.adoc
@@ -108,6 +108,10 @@ 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.
 
+SEE ALSO
+--------
+linkgit:git-cherry[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite

-- 
2.53.0.26.g2afa8602a26

Ben Knoble· Feb 14, 2026, 20:00 UTC · re: kristofferhaugsbakk@fastmail.com · lore

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

Show 99 quoted lines

> Le 14 févr. 2026 à 06:56, kristofferhaugsbakk@fastmail.com a écrit :
> 
> 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
>

Looks like my comments were well-addressed, thanks! Looks good.

Junio C Hamano· Feb 20, 2026, 22:31 UTC · re: kristofferhaugsbakk@fastmail.com · lore

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

kristofferhaugsbakk@fastmail.com writes:

Show 8 quoted lines

> 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/

The latest iteration of this series has seen no responses. Is everybody happy with them?

Thanks.

Ben Knoble· Feb 21, 2026, 02:38 UTC · re: Junio C Hamano · lore

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

Show 17 quoted lines

> Le 20 févr. 2026 à 17:31, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> kristofferhaugsbakk@fastmail.com writes:
> 
>> 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/
> 
> The latest iteration of this series has seen no responses.  Is
> everybody happy with them?
> 
> Thanks.

No /further/ responses, perhaps? Unless my mail didn’t come through. I completely understand if my approval was not weighted particularly highly, though, ;)

Kristoffer Haugsbakk· Feb 23, 2026, 18:04 UTC · re: Ben Knoble · lore

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

On Sat, Feb 21, 2026, at 03:38, Ben Knoble wrote:

Show 21 quoted lines

>> Le 20 févr. 2026 à 17:31, Junio C Hamano <gitster@pobox.com> a écrit :
>>
>> kristofferhaugsbakk@fastmail.com writes:
>>
>>> 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/
>>
>> The latest iteration of this series has seen no responses.  Is
>> everybody happy with them?
>>
>> Thanks.
>
> No /further/ responses, perhaps? Unless my mail didn’t come through. I
> completely understand if my approval was not weighted particularly
> highly, though, ;)

Thanks for following this series.

I was wondering if a relatively lengthy example like that would be accepted on such a small (doc footprint) command. I was ready to drop that example patch/commit if the series didn’t move ahead.

In general *I* would like to see more examples and discussions in the docs where commands that are better used in conjunction with other Git commands and general utilities (c.f. git-commit(1), git-tag(1), ...). And in this case, this “write a script for it” command, as it was called in the linked email,[1] seemed like a good candidate.

† 1: https://lore.kernel.org/workflows/CAHk-=wiN+8EUoik4UeAJ-HPSU7hczQP+8+_uP3vtAy_=YfJ9PQ@mail.gmail.com/

It’s a bit hard to find information on this on the Web, I think, because “Git plumbing” has been SEO’ed into the silo of “here’s how you can use three Git plumbing commands to do what you can do in one Git porcelain command”.

But I also can understand if others think (maybe?) think that this would be too much verbiage.

But I see that this is in `next` now. Which I am glad to see of course.