doc: clarify `git range-diff` add/delete output
What the developer wrote
Authored by Lőrinc
doc: clarify `git range-diff` add/delete output
When `git range-diff` cannot match a commit between two versions of a branch, it shows the old commit as removed (`<`) and the new commit as added (`>`), and it does not show the patch contents.
This output is easy to misread as "no code changes" because the diff for that commit is effectively empty.
It really means the commits were considered unrelated and the new commit should be reviewed from scratch.
This is analogous to rename detection in `git diff`: if similarity is too low, a rename shows up as delete+add.
Example (exact SHAs from PR #34320):
B=ff338fdb53a66ab40a36e1277e7371941fc89840; A=dd76338a57b9b1169ac27f7b783d6d0d4c6e38ab; git fetch upstream $B $A
git range-diff 0ca4295f2e5f4443a1f8b3bae7cba0f6c054276f..$B 139aa4b27e4839291c83a04dcd1649c5595814ca..$A
This produced output like:
1: 4b32181dbb < -: ---------- test: add `HaveInputs` call-path unit tests
-: ---------- > 1: 277c57f0c5 test: add `HaveInputs` call-path unit tests
Even though the subject matches, the first commit had no matching diff shown.
That should be treated as "unmatched" rather than "unchanged".
If you expected a match, try increasing the creation factor so `git range-diff` searches harder:
git range-diff --creation-factor=95 <old_range> <new_range>
What changed, and why it matters
This commit only updates developer documentation (doc/productivity.md) to explain how to correctly read `git range-diff` output. It contains no code changes, no configuration changes, and no security-relevant behavior. It is purely a documentation clarification about a Git tool used during code review.
No security action needed. This is a documentation-only change and can be reviewed as normal project documentation.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch adds a note and example to Bitcoin Core’s productivity guide explaining that git range-diff may display unmatched commits as removed/added pairs without patch contents, and suggests using --creation-factor=95 to improve matching. The diff touches only Markdown documentation; no source code, build system, tests, or runtime logic is modified.
Changed components
doc/productivity.mdInspect captured patch +12 / −1
diff --git a/doc/productivity.md b/doc/productivity.md
index 4509e23c..c436811a 100644
--- a/doc/productivity.md
+++ b/doc/productivity.md
@@ -191,7 +191,12 @@ Then a simple `git pr 12345` will fetch and check out that pr from upstream.
### Diff the diffs with `git range-diff`
-It is very common for contributors to rebase their pull requests, or make changes to commits (perhaps in response to review) that are not at the head of their branch. This poses a problem for reviewers as when the contributor force pushes, the reviewer is no longer sure that his previous reviews of commits are still valid (as the commit hashes can now be different even though the diff is semantically the same). [git range-diff](https://git-scm.com/docs/git-range-diff) (Git >= 2.19) can help solve this problem by diffing the diffs.
+It is very common for contributors to rebase their pull requests, or make changes to commits (perhaps in response to review) that are not at the head of their branch. This poses a problem for reviewers as when the contributor force pushes, the reviewer is no longer sure that their previous reviews of commits are still valid (as the commit hashes can now be different even though the diff is semantically the same). [git range-diff](https://git-scm.com/docs/git-range-diff) (Git >= 2.19) can help solve this problem by diffing the diffs.
+
+> [!NOTE]
+> If `git range-diff` cannot match a commit in the old range to a commit in the new range, it will show it as "removed" (`<`) and "added" (`>`), without showing the patch contents.
+> This does not mean there were no code changes.
+> It means the commit was considered unrelated, and should be reviewed in full like a new commit.
For example, to identify the differences between your previously reviewed diffs P1-5, and the new diffs P1-2,N3-4 as illustrated below:
```
@@ -207,6 +212,12 @@ You can do:
git range-diff master previously-reviewed-head new-head
```
+If you expected `git range-diff` to match a commit, but it shows it as a deletion and an addition, try re-running with a higher creation factor:
+
+```sh
+git range-diff --creation-factor=95 <old_range> <new_range>
+```
+
Note that `git range-diff` also works for rebases:
```
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.