git range-diff: see what an agent changed when it rewrites your history
TL;DR: git range-diff <range1> <range2> compares two versions of a patch series and pairs up the commits that correspond, printing = for an equivalent patch, ! for one that changed, and < / > for commits that only exist on one side. That makes it the command you want when an agent rebased, squashed, or reworded its own work and you need to know what actually moved, without reading every diff twice. Matching is fuzzy by design, and the --creation-factor knob (60 percent by default) is what decides how similar two patches have to be to count as the same patch.
What you’ll be able to do:
- Compare “the branch as the agent left it” against “the branch as it should be” and get a per-commit verdict instead of a wall of diffs.
- Recognise the four output markers and what each one tells you about the change.
- Tune
--creation-factorso a rewritten patch is shown as modified instead of being reported as one deletion plus one addition. - Use
git range-diffas the review step after a rebase, before you push the agent’s branch.
Honest take:
range-diffcompares patches, not behaviour. It tells you that one hunk changed; it cannot tell you the changed hunk is the one that broke your build. Pair it with a test run, not with a second pair of eyes.
Why a normal diff is the wrong tool after an agent rebase
An agent that reworks a branch changes the commit hashes without necessarily changing the code. Three commits become one, a commit message is rewritten, a hunk moves to a different file, and the net result of the branch is identical to what you approved. Now look at git diff main..branch: it is empty, or nearly so, and it tells you nothing about the four intermediate commits the agent created on the way there.
This is where an ordinary diff stops helping. git diff compares two trees. When the trees match, the diff is empty, and the history — the part a reviewer actually reads — is invisible. git log shows the new commits but not how they relate to the old ones.
git range-diff sits between the two. The official manual, checked November 16, 2026, describes it as a command that “shows the differences between two versions of a patch series, or more generally, two commit ranges (ignoring merge commits)”. The way it works: it first finds pairs of commits from both ranges “that correspond with each other”, where two commits correspond when “the diff between their patches (i.e. the author information, the commit message and the commit diff) is reasonably small compared to the patches’ size”. The matched pairs are then listed in the order of the second range, with unmatched commits inserted just after their ancestors.
That correspondence rule is the whole idea. It is not a hash comparison and not a cherry-pick detection; it is a similarity judgement over the patch itself.
The four markers, and what each one costs you
Run against two ranges, every commit on the left and every commit on the right gets a line. The symbol between them is the verdict.
| Marker | Meaning | What you have to do |
|---|---|---|
= | The two patches correspond and are equivalent | Nothing |
! | The patches correspond but the content changed | Read the inline diff below the line |
< | This commit exists only in the first range | Decide whether the work was dropped on purpose |
> | This commit exists only in the second range | Read it — this is new work nobody reviewed |
The inline diff under a ! line is the part that pays for the whole command. It shows the changed hunk and nothing else, so you read one small block instead of a full patch.
I built a throwaway repository to capture the real output. Series A was three commits on main: add a parse helper, strip whitespace in it, add a format helper. Series B was the same three patches replayed on top of a new upstream commit, with one deliberate change — the format helper returning str(y).upper() instead of str(y). git range-diff main..agent upstream..agent-rebased printed:
1: 1e3101e = 1: 43a2dfa feat: add parse helper
2: bab843f = 2: 86d2533 fix: strip whitespace in parse
3: 60444f4 ! 3: fb98c74 feat: add format helper
@@ app.py: print('hello')
return int(x)
return int(x.strip())
+def format(y):
-+ return str(y)
++ return str(y).upper())
Two commits were equivalent despite having completely different hashes, because they had been replayed onto a different base. The third is the one that actually changed, and the diff shows exactly one line changing. The exit status was 0.
Note what the ordinary diff said about the same two branches: git diff --stat main..agent and git diff --stat upstream..agent-rebased both reported the same five inserted lines. The tree diff could not tell you that one line of the new series was different, because that difference was introduced inside the rewritten history and then cancelled out by the surrounding context.
--creation-factor is the dial that decides matched or not
Pairing is a cost calculation, and the cost is normalised by the size of the patch. The manual exposes the threshold as an option:
--creation-factor=<percent>— Set the creation/deletion cost fudge factor to<percent>. Defaults to 60. Try a larger value if git range-diff erroneously considers a large change a total rewrite (deletion of one commit and addition of another), and a smaller one in the reverse case.
So a patch that has drifted more than roughly 60 percent away from its counterpart is no longer considered the same patch. It is reported as one commit deleted and one commit added — which reads like “the agent rewrote this from scratch”, when in fact it tweaked one line.
In the fixture above, re-running with --creation-factor=10 changed the third line from ! to a deletion plus an addition:
3: 60444f4 < -: ------- feat: add format helper
-: ------- > 3: fb98c74 feat: add format helper
The one-line change stopped counting as “the same patch” once the bar was lowered. That is the behaviour to expect in the other direction too: a heavy rewrite looks like a rewrite at the default factor, and --creation-factor=90 will make git treat the old and new patches as the same commit with modifications, which is often what you want when the agent reformatted a whole file.
Two more options matter when the ranges are not symmetric. --left-only suppresses commits missing from the first range, and --right-only suppresses commits missing from the second. Use --right-only when you only care what the agent added relative to the reviewed series; use --left-only when you are hunting for work that got dropped. --no-dual-color turns off the “dual coloring” where unchanged context is dimmed and new lines are bold, which is what you want when you are piping the output into a file or a review comment. --notes and --no-notes control whether commit notes are included.
Range syntax: three forms, one idea
The manual documents three ways to name the ranges:
| Form | Meaning | Use it for |
|---|---|---|
<range1> <range2> | Two ranges, each of the form <base>..<rev>, <rev>^!, or <rev>^-<n> | The normal case: compare two branches |
<rev1> ... <rev2> | Equivalent to <rev2>..<rev1> <rev1>..<rev2> | Comparing two revisions of the same branch |
<base> <rev1> <rev2> | Equivalent to <base>..<rev1> <base>..<rev2> | Two branches that share a base |
The practical form for an agent workflow is the three-argument one, because both sides get the same base:
# what did the agent's rewritten series change relative to the approved one?
git range-diff main..feature-approved main..feature-agent
# only the commits that are new on the agent's side
git range-diff --right-only main..feature-approved main..feature-agent
# treat heavy rewrites as modifications instead of delete + add
git range-diff --creation-factor=90 main..feature-approved main..feature-agent
Path arguments limit the comparison, the same way they limit a normal diff: git range-diff main..a main..b -- src/. Merge commits are ignored by default; --diff-merges=<format> passes the format through to git-log, and --remerge-diff recomputes the merge result so you can see what a re-merge would produce.
Where this sits in the rest of the review chain
range-diff answers a question none of the other review commands answer: not “what does the tree look like now” and not “what did this one commit do”, but “how does this series of commits relate to that other series”. It pairs naturally with the rest of the checks an agent-driven branch needs:
- Use the merge-base check first to make sure you are diffing against the right base, then use
range-diffon top of that base. - Use
git diffexit codes when you script the review, because--exit-codeis what makes a difference detectable in a pipeline. - When the agent left staged and untracked files behind, the staged-diff inventory is the check that catches them, since
range-diffonly looks at commits. - When you need to know which commit introduced a regression rather than what changed,
git bisect runis the tool with a test-driven contract. - When the agent’s branch is one of several parallel attempts, isolating each task in its own worktree keeps the ranges comparable in the first place.
Honest take: what range-diff cannot tell you
It compares patches. It does not judge them.
- A matched patch can still be wrong. The
=marker means the two patches are equivalent, not that either of them is correct. - Similarity is not intent. Two commits that touch the same lines with the same words pair up even when one of them was meant to solve a different problem.
- The author information is part of the comparison. The manual lists author information, commit message, and commit diff as the inputs to the correspondence test, so a reworded commit message shifts the cost of the pairing. That is why an agent that rewrites its commit messages can make a series look more changed than it is.
- Merge commits are invisible by default. If the agent’s series contains merges,
range-diffskips them unless you pass--diff-merges. - It says nothing about runtime. A
!line tells you a hunk changed. Only running the code tells you whether the change is the bug. The same discipline applies to the diff-scope checks in the rename-detection budget guide: a cheap pre-filter, never a verdict.
Use it as the last step before you push an agent’s branch: if every line is =, the branch is the same work it was yesterday. If there is a !, that one hunk is the review you still owe.
Sources
- git-range-diff manual: description, range syntax,
--creation-factor,--left-only,--right-only,--no-dual-color— git-scm.com - git-revisions: range specification forms (
<base>..<rev>,<rev>^!,<rev>^-<n>) — git-scm.com - git-log
--diff-mergesand--remerge-diffoptions — git-scm.com - git-diff: patch-notation and diff options accepted by
range-diff— git-scm.com - git-bisect manual — git-scm.com
Last updated November 16, 2026. The git range-diff behaviour above was checked against the current git-scm.com manual and reproduced locally with Git 2.47.3 in a throwaway repository. The output blocks are real fixture output, not illustrations. No hosted service, paid API, or model inference was involved.
Was this article helpful?
Thanks for the feedback — it helps improve future articles.
Need hands-on help?
I offer 1-on-1 technical consulting for local AI setup, GPU selection, and AI coding tool configuration — same topics covered on this site.
Book a session — $49 / hour →Know which coding tool is worth paying for
Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.