Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash Compare a branch before and after an amend

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.

Bash Dropped and added commits

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

Terminal
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-diff still 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 with 1:).
  • = 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-factor when a heavily edited commit is reported as < plus >. Raising it makes range-diff try 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.