Git Reference ยท Merging and Rebasing
git range-diff command
Reference for git range-diff: compare two versions of a branch after a rebase or amend, read the =, !, < and > markers, and tune matching with --creation-factor.
git range-diff compares two ranges of commits and shows what changed between them. It is made for the moment after you rewrite a branch (rebase, amend, squash, reorder) and want to know exactly what the rewrite did: which commits survived untouched, which ones changed, and which ones were dropped or added.
A normal git diff between the old and new tip only shows the final difference in the files. range-diff pairs up the commits of the two series by their patch content and subject, and then shows a "diff of diffs" for every pair that is not identical. Reviewers use it to read the next version of a patch series without reading everything again.
git range-diff main topic-v1 topic-v2 git range-diff main..topic-v1 main..topic-v2 git range-diff topic-v1...topic-v2
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git range-diff [<diff-options>] [--creation-factor=<percent>] [--left-only | --right-only] [--[no-]dual-color] ( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> ) [[--] <path>...]
The three argument forms describe the two series:
| Form | Meaning |
|---|---|
<range1> <range2> |
Two explicit ranges such as main..v1 main..v2. |
<rev1>...<rev2> |
Symmetric difference: each side is the set of commits the other tip cannot reach. Handy for two versions of a branch that share their base. |
<base> <rev1> <rev2> |
Shorthand for <base>..<rev1> <base>..<rev2>. The most common form. |
| Option | Description |
|---|---|
--creation-factor=<percent> |
How much a commit may differ and still count as "the same commit, changed" instead of "dropped plus added". Default 60. Larger values pair more commits. |
--left-only, --right-only |
Hide commits that exist only in the other range. |
--[no-]dual-color |
With color, show the difference of the two diffs in two layers. On by default when color is on. |
--[no-]notes |
Include or exclude commit notes in the compared messages. |
--no-patch |
Show only the matching table, without inner diffs. |
<diff-options> |
Options such as --stat or -w are passed on to the inner diffs. |
Output. Each line reads <n>: <old-id> <marker> <m>: <new-id> <subject>. The marker is one of:
| Marker | Meaning |
|---|---|
= |
The commit has the same patch in both ranges. |
! |
A matching commit with a different patch (an inner diff follows). |
< |
The commit exists only in the first range (dropped). |
> |
The commit exists only in the second range (added). |
Usage notes
- Matching is by patch, not by ID. After a rebase every commit gets a new ID, but
range-diffstill pairs the old and new versions because the changes and subjects look alike. - Order does not have to be the same. A reordered series shows up with the numbers on each side out of step (for example
2:paired with1:). =hides base changes. A commit only counts as unchanged when its diff is identical, so rebasing onto a newer base without conflicts produces only=lines. That is exactly the check you want.- The inner diff compares patches. Lines in it show what changed in the change. Context shifts caused by a new base are filtered out.
- Use
--creation-factorwhen a heavily edited commit is reported as<plus>. Raising it makesrange-difftry harder to pair them. - Compare linear series. The command is designed for ranges without merge commits.
- Related for review: mailing-list style workflows put the output in the cover letter of the next patch version.
git format-patch --range-diff=<previous>does this for you.
Related
git rebase,git cherry,git log,git diff- Lessons: Rebase, Interactive rebase