@matheusbsbs / matheus-bagliano / commits / 795d41db13

doc: patch-id: add script example

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Kristoffer Haugsbakk committed Feb 14, 2026 at 12:55 UTC 795d41db1304cdba06361916fa64f93c44678228
1 file changed +40
Documentation/git-patch-id.adoc
+40
@@ -68,6 +68,46 @@ This is the default if `patchid.stable` is set to `true`.
68 +
69 This is the default.
70
71 +EXAMPLES
72 +--------
73 +
74 +linkgit:git-cherry[1] shows what commits from a branch have patch ID
75 +equivalent commits in some upstream branch. But it only tells you
76 +whether such a commit exists or not. What if you wanted to know the
77 +relevant commits in the upstream? We can use this command to make a
78 +mapping between your branch and the upstream branch:
79 +
80 +----
81 +#!/bin/sh
82 +
83 +upstream="$1"
84 +branch="$2"
85 +test -z "$branch" && branch=HEAD
86 +limit="$3"
87 +if test -n "$limit"
88 +then
89 + tail_opts="$limit".."$upstream"
90 +else
91 + since=$(git log --format=%aI "$upstream".."$branch" | tail -1)
92 + tail_opts=--since="$since"' '"$upstream"
93 +fi
94 +for_branch=$(mktemp)
95 +for_upstream=$(mktemp)
96 +
97 +git rev-list --no-merges "$upstream".."$branch" |
98 + git diff-tree --patch --stdin |
99 + git patch-id --stable | sort >"$for_branch"
100 +git rev-list --no-merges $tail_opts |
101 + git diff-tree --patch --stdin |
102 + git patch-id --stable | sort >"$for_upstream"
103 +join -a1 "$for_branch" "$for_upstream" | cut -d' ' -f2,3
104 +rm "$for_branch"
105 +rm "$for_upstream"
106 +----
107 +
108 +Now the first column shows the commit from your branch and the second
109 +column shows the patch ID equivalent commit, if it exists.
110 +
111 GIT
112 ---
113 Part of the linkgit:git[1] suite