git range-diff: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git range-diff shows how a series of commits changed between two iterations - a diff of diffs.

range-diff is invaluable after a rebase or force-push: it tells you what actually changed between the old and new series.

What it does

git range-diff matches up commits from two ranges and shows how each changed, making it easy to review what a rebase or amended series altered beyond just moving the base.

Common usage

git range-diff main..@{u} main..HEAD
git range-diff old-base new-base
git range-diff <base> <old-tip> <new-tip>
git range-diff --creation-factor=80 A...B

Options

Common errors in CI

fatal: need two commit ranges - range-diff requires two ranges (or the base/old/new triple). Mis-specifying ranges yields confusing "all commits new" output; ensure both ranges share a base, and that full history is present (not a shallow clone).

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation