Re: [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(+)
>
> 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
>
>