gritHEAD → docs/patch-id
Commands / PlumbingMarkdown

grit patch-id

Stable patch-IDs for commits (cherry-pick equivalence).

grit patch-id <REV|RANGE>...
grit patch-id --unstable <REV|RANGE>...

Description

Prints one line per commit that has a defined patch-ID: <patch-id> <commit>, matching git show --format= --no-ext-diff -U3 <REV> | git patch-id --stable on the commit's tree diff. Text hunks include three unchanged context lines on each side; nearby context contributes to the ID, while unchanged lines outside the hunks do not. Hunks come from the same diff as grit diff and Git's default (Myers with the indent heuristic), so an insertion or deletion that could slide to several equally short positions is hashed where Git places it; a final line without a newline never counts as equal to the same text with one. In stable and unstable modes spaces, tabs, carriage returns and newlines are dropped before hashing, while other control characters such as form feed still count, as in Git. A submodule pointer (gitlink) is hashed as its Subproject commit <oid> line, so the submodule's commit never has to exist in this repository, and a path that changes type (for example a file replaced by a symlink or a submodule) is hashed as a deletion plus an addition, as git show prints it. Merge commits and commits with no file changes are omitted.

A range argument expands to one line per commit, in the same order as grit revs:

  • A..B lists the commits reachable from B but not from A, such as the commits of a branch since it left main.
  • A...B lists the commits on both sides of the symmetric difference as one sequence, without saying which side each came from. To compare two versions of a rewritten branch, use grit revs --cherry-mark A...B, which pairs the sides by patch-ID.

Any other argument names one commit. Output follows argument order, so a commit named twice is printed twice.

Uses Repository::patch_ids_for_revs with stable accumulation (file order independent). Pass --unstable for the legacy Git 1.9 algorithm.

Benchmarking

Compare the same commit with the installed system Git:

$ /usr/bin/time -v grit patch-id HEAD --json
$ /usr/bin/time -v sh -c 'git show --format= --no-ext-diff -U3 HEAD | git patch-id --stable'

Use a large text file with sparse edits to measure hunk traversal rather than only process startup. Record wall time and peak resident memory with warm object caches; use the dist profile when building grit locally.

Measured on 2026-10-26 on Linux x86_64 (4 vCPUs, AMD EPYC 9V74), using a 14 MB file with 200,000 unique lines and ten replacements spaced 20,000 lines apart. Both grit binaries use the dist profile. Results are medians of 21 interleaved warm-cache runs per command after one warm-up; peak RSS comes from /usr/bin/time -v for each invocation.

Implementation Wall time Median peak RSS Peak RSS range
System Git 2.55.0 62.91 ms 62,604 KiB 61,696–63,240 KiB
Grit before fix (fa6a9fd55) 175.43 ms 100,732 KiB 100,008–101,892 KiB
Grit with three context lines 146.02 ms 101,632 KiB 100,800–101,988 KiB

The fix reduces median wall time by 17%. Median peak RSS differs by 900 KiB (0.9%), with overlapping observed ranges. The fixed result matches system Git's patch-ID for a normal unified diff on this fixture.

Ranges hash their commits on worker threads. Measured on 2026-10-27 on Linux x86_64 (4 vCPUs) with system Git 2.43.0 and a release build of grit, in a packed repository with a commit-graph: 5,000 base commits, a 100-commit branch rebased onto 200 new upstream commits (old...new has 400 commits). Means of 30 warm runs (hyperfine):

Command Wall time Peak RSS
git rev-list old...new | git diff-tree --stdin -p | git patch-id --stable 20.3 ms —
grit patch-id old...new 17.6 ms 23,576 KiB
git rev-list --left-right --cherry-mark old...new 10.2 ms 8,392 KiB
grit revs --cherry-mark old...new 22.9 ms 26,444 KiB

Git's cherry-mark compares a cheap file-header id before computing a full patch-ID; grit computes the full ID for every commit, which accounts for most of the remaining gap.

Options

Option Description
--unstable Use unstable patch-ID hashing instead of stable (default).

JSON output

Schema: v1

Field Type Meaning
entries array Each item has patch_id and commit (full hex object ids), in argument order with ranges expanded.

Markdown output

Schema: v1

--markdown prints a table of patch IDs and commits.

Exit status

Code Meaning
0 Success (success).
1 Command failed (failure).
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.