git range-diff 的核心区别在于它是专为 patch series 设计的语义对比工具，逐个匹配提交并比对 author、message 和 diff 内容，而非仅比较快照状态；它默认忽略 merge 提交，通过 patch signature 相似度配对，支持三种参数形式（如 或 ），顺序影响匹配逻辑，且需共同祖先以确保正确对齐。
git range-diff 和 git diff 的核心区别在哪
不是“更高级的 diff”，而是专为 patch series 设计的语义对比工具。当你在重构分支（比如 rebase 或 am 后的版本迭代）时，git diff A B 只比两个 commit 快照，而 git range-diff 会逐个匹配提交——把 A 中的 feat/login 提交和 B 中语义相近的 refactor/auth-flow 提交对齐，再比它们的 author、message、diff 内容是否实质变化。
常见错误现象：用 git diff main..feature-v2 main..feature-v1 想看重构差异，结果输出一堆文件变更，但根本看不出哪个提交被拆了、哪个被合并了、哪个只是改了 message。这就是没用对工具。
-
git diff看的是「最终状态差」，适合单次快照对比 -
git range-diff看的是「补丁序列演化」，适合 PR 多轮修订、RFC 迭代、邮件列表 patch series 审阅 - 它默认忽略 merge 提交，也不处理重命名或大幅重写——除非你调
--creation-factor
怎么写对 range-diff 的参数顺序
三种合法形式，但最容易出错的是第一种：<range1><range2></range2></range1>。它要求你明确谁是“旧版”、谁是“新版”，且顺序直接影响匹配逻辑。
假设你刚 rebase 完 feature 分支，想对比 rebase 前后两组提交：
- ✅ 正确：
git range-diff origin/main..feature-old origin/main..feature-new—— 左边是旧 patch series，右边是新 patch series - ❌ 错误：
git range-diff origin/main..feature-new origin/main..feature-old—— 匹配算法仍以左边为基准找对应，但语义上你本想“看新版改了啥”，结果输出全是“旧版有、新版没了”的条目，容易误判为删功能 - ✅ 更稳写法（推荐）：
git range-diff base-commit feature-old feature-new，等价于base-commit..feature-old base-commit..feature-new，避免范围表达式歧义
注意：base-commit 必须是两个分支共同祖先，否则匹配会失效——可用 git merge-base feature-old feature-new 先确认。
为什么有些提交总被标成 “unmatched”
这不是 bug，是 git range-diff 的匹配策略在起作用：它先算每个提交的“patch signature”（author + subject + diff hash），再按相似度阈值配对。当重构导致某个提交被拆成两个、或两个合并成一个，signature 就断了。
典型场景：
- 原提交
fix: handle null in api response被拆成refactor: extract validation logic+fix: guard against null - 原三个小提交被 squash 成一个大提交，diff size 超过默认
--creation-factor=60的容忍范围
这时可调参缓解：
- 加大
--creation-factor=80，让算法更倾向认为“大 diff = 重写而非新增/删除” - 加
--no-dual-color避免颜色干扰判断（尤其终端不支持真彩时） - 用
--left-only或--right-only单独看某一边未匹配项，定位具体哪几个提交“失联”
但别指望它 100% 自动对齐——人工核对 git log --oneline 输出仍是必要步骤。
如何结合 VSCode 快速审查 range-diff 结果
git range-diff 输出是纯文本，但直接丢进 VSCode 编辑器就能获得语法高亮和折叠能力，比终端滚动更高效。
实操建议：
- 导出到文件：
git range-diff base old new > range-diff.out，然后用 VSCode 打开 - 搜索
^或+快速跳转到 unmatched 提交块（开头标记为1: abcdef... ! 2: ghijkl...或1: abcdef... +） - 对关键 unmatched 提交，右键复制其 SHA，再用
git show <sha></sha>单独看内容，验证是否真为逻辑等价 - VSCode 插件如 GitLens 不支持 range-diff 解析，别白费劲启用它
真正容易被忽略的点：range-diff 不比较工作区或暂存区，只基于 commit tree。如果你的重构还包含未 commit 的本地修改，它完全看不到——务必先 git add && git commit 再跑。
