git-range-diff 教程

一句话理解

git range-diff 比较的是“两段提交序列之间的补丁变化”，不是单个提交或两个目录快照。

什么时候最有价值

• 你对分支做了 rebase / squash / 重排后，想说明版本差异
• reviewer 问“v2 相比 v1 到底变了什么”
• 你要确认历史整理是否意外丢补丁或引入额外修改

典型命令

git range-diff origin/main...feature-v1 origin/main...feature-v2

含义是：都以 origin/main 为基线，比较 feature-v1 与 feature-v2 两组补丁序列。

它和 git diff 的区别

这是一个纯只读的比较工具，不修改任何提交或引用。可以放心使用。

• git diff：看“最终文件差异”
• git range-diff：看“补丁序列如何变化”

两者都重要，但回答的问题不同。

推荐操作流程

1. 保留旧版本分支或 tag（如 feature-v1）
2. 在新版本完成后运行 range-diff
3. 把关键差异摘要写进 PR 说明

git fetch origin
git range-diff origin/main...feature-v1 origin/main...feature-v2

这条命令在流程里解决什么问题

git range-diff 是一个纯只读的比较工具，不修改任何提交或引用。它的作用是对比两组提交序列之间的差异——最常用于 rebase 前后，看看提交被改动了什么。它不会重塑历史，但能帮你理解历史被重塑后的变化。

典型用例

• rebase 之后用 git range-diff 对比 rebase 前后，确认只有预期的改动被修改。
• 在 review 流程中，用 git range-diff v1 v2 展示两轮补丁集的差异，让 review 者看到具体变化。
• 用三点语法 git range-diff origin/main...v1 origin/main...v2 比较两个特性分支版本的差异。

图例理解

输入

提交范围 A（如 v1）提交范围 B（如 v2）

→git range-diff

结果

匹配对应关系变更差异新增或删除的提交

range-diff 是只读操作，通过 patch-id 和作者信息匹配对应提交，不修改仓库任何状态。

常见误区

误区 1：把它当成文件 diff

• 如果两组提交序列差异很大（比如完全重写），range-diff 的匹配结果可能不够直观，需要结合 git diff 手动确认。
• range-diff 的三点语法 A...B 会自动以 merge-base 为起点，与 git diff A...B 的逻辑一致。
• 输出格式与 git diff 类似，但多了提交对应关系（- = 删除、+ = 新增、! = 修改）。
• 这是一个纯只读命令，不会修改仓库的任何状态。

这样会误解输出语义，错过“补丁级变化”信息。

误区 2：没有固定基线就直接比较

基线不同会导致结果噪声很大。

误区 3：整理历史后不做 range-diff

容易把“看似等价”的历史重写带入不可见偏差。

接下来建议继续看什么

1. prepare commits before pull request
2. stacked pull requests workflow
3. git-rebase 搭配 git log --oneline --graph、git diff 和 git rebase 一起理解，可以更全面地掌握如何安全地审查和比较提交序列的变化。