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

> git range-diff compares two versions of a commit series to show what changed between iterations. Reference for the dual-range syntax and --creation-factor.

Source: https://latchkey.dev/learn/command-reference/git-range-diff  
Updated: 2026-06-25

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

```Terminal
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

| Form / flag | What it does |
| --- | --- |
| <r1> <r2> | Compare two symmetric ranges |
| <base> <old> <new> | Three-arg form with a common base |
| --creation-factor=<n> | Tune commit pairing heuristic |
| --no-color-moved | Disable moved-line coloring |

## 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

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

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 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).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt