Git Range-Diff: Compare Commit Series

Advanced

Learner goal

By the end of this lesson, you should be able to use `git range-diff` to compare two versions of a commit series, understand how Git pairs corresponding patches, recognize additions/removals and changed patches, and choose a focused range, output, or path restriction without confusing patch-series comparison with an ordinary file diff.

What `git range-diff` compares

`git range-diff` compares two versions of a commit series. Git ignores merge commits when constructing the series, then attempts to pair commits whose author information, commit message, and patch are sufficiently similar. The result is ordered by the second series and shows commits that disappeared, appeared, or changed.

git range-diff <old-base>..<old-tip> <new-base>..<new-tip>

?

The three range forms

The official manual documents three equivalent ways to describe the two series. Two explicit ranges use `<base>..<tip>` forms. A symmetric `<rev1>...<rev2>` form compares the two sides from their merge-base-style endpoints. A three-revision form gives one base followed by the old and new tips.

git range-diff OLD_BASE..OLD_TIP NEW_BASE..NEW_TIP
git range-diff OLD_TIP...NEW_TIP
git range-diff BASE OLD_TIP NEW_TIP

?

Read the correspondence markers

The left number identifies a commit in the first series and the right number identifies a commit in the second. An `=` marker indicates a close match; `!` indicates a corresponding patch whose details changed; a `<` or `>` indicates a commit present only on the left or right series. The displayed patch difference explains how a matched commit changed.

git range-diff BASE..OLD_TIP BASE..NEW_TIP

?

Reviewing a rebased or revised series

A common use is checking what changed when a topic branch was rebased or otherwise revised. Keep the old and new series fixed while reviewing the output. A matched pair means Git found corresponding patches; the inner diff then shows changes to the author/message/patch representation of that pair.

git range-diff topic@{u} topic@{1} topic

This three-revision form is useful after a rebase when the upstream tip, previous topic tip, and current topic tip identify the two versions you want to compare. The exact revisions depend on the repository's reflog and tracking state.

Control patch pairing and output

`--creation-factor=<n>` changes how strongly Git favors pairing a newly created patch with an existing patch when their similarities are borderline. `--left-only` and `--right-only` suppress the opposite side's unmatched output. `--no-dual-color` uses the simpler diff coloring instead of preserving the inner patch colors while adding outer change markers.

git range-diff --creation-factor=80 OLD_BASE..OLD_TIP NEW_BASE..NEW_TIP
git range-diff --left-only OLD_BASE..OLD_TIP NEW_BASE..NEW_TIP
git range-diff --right-only OLD_BASE..OLD_TIP NEW_BASE..NEW_TIP
git range-diff --no-dual-color OLD_BASE..OLD_TIP NEW_BASE..NEW_TIP

?

Use ordinary diff options carefully

`git range-diff` accepts regular diff output options, including `--color`, `--stat`, path restrictions, and many other diff controls. These options affect the comparison of the patches; they do not turn range-diff into a stable machine-readable interchange format.

git range-diff OLD_BASE..OLD_TIP NEW_BASE..NEW_TIP -- src/

A disciplined workflow

First identify the old and new series and a meaningful common base. Run an unmodified range-diff and inspect which commits pair. Then investigate `!` pairs by reading the inner patch difference. If pairing is ambiguous, try an appropriate creation factor rather than assuming commit positions correspond. Restrict to a path only when the review question is genuinely path-specific. Treat `--left-only` and `--right-only` as review filters, not as proof that the underlying series is semantically equivalent.

git range-diff BASE..OLD_TIP BASE..NEW_TIP
git range-diff --creation-factor=80 BASE..OLD_TIP BASE..NEW_TIP -- src/

What `git range-diff` does not own

`git range-diff` does not rewrite history, rebase a branch, apply patches, or compare arbitrary working-tree snapshots. Use `git rebase` for rewriting a series, `git apply` or the patch workflow for applying patch text, and `git diff` when the question is simply how two trees or states differ. It also does not replace `git log` when you need chronological history rather than patch-series correspondence.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official source boundary

This lesson uses the official Git `git-range-diff` documentation for command semantics and the official Git revision-range and diff documentation as referenced by that manual. No third-party documentation is used for command semantics.