From bfd125f64f86e78894d67c9eafdbae38779484bc Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 14 Feb 2026 12:55:41 +0100 Subject: [PATCH 1/3] doc: patch-id: emphasize multi-patch processing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- Documentation/git-patch-id.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc index 013e1a6190..e95391cd25 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 ------- From 795d41db1304cdba06361916fa64f93c44678228 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 14 Feb 2026 12:55:42 +0100 Subject: [PATCH 2/3] doc: patch-id: add script example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- Documentation/git-patch-id.adoc | 40 +++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc index e95391cd25..1618994e76 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 From ed84bc1c0da0c5a972459f639801bc7ec235084c Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sat, 14 Feb 2026 12:55:43 +0100 Subject: [PATCH 3/3] doc: patch-id: see also git-cherry(1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- Documentation/git-patch-id.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/git-patch-id.adoc b/Documentation/git-patch-id.adoc index 1618994e76..05859990c8 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