企业官网建设流程全解析

• 桌面应用
• 版本控制
• 开发工具

Git 的提交历史本质上是一张由父提交指针构成的图，理解"可达提交"（reachable commit）与"不可达提交"（unreachable commit）是准确解读git diff、合并历史与提交范围的关键。本文以 GitHub Desktop（本仓库 desktop 项目）为背景，从概念、Git 命令行为到 diff.ts 与 app-store.ts 中的真实实现，完整讲解祖先路径如何决定一次 diff 到底包含哪些提交的变更，以及为什么在包含合并提交的分支上做多提交范围选择时会"丢失"某些变更。

什么是可达与不可达提交

在 Git 中，除了仓库的第一个提交外，每个提交至少有一个父提交；而一个仓库可以在任意提交上长出任意数量的分支。因此，我们可以沿着"一个提交的父提交 → 再一个父提交"的路径，构造出整个提交历史图。所谓可达提交，就是能够从某个提交出发、沿着父提交指针一路回溯到达的提交；这条回溯路径称为该提交的祖先路径（ancestral path）。

以一个main分支为例，其首个提交为A，随后追加提交B和C，历史图如下：

从C出发可以沿C -> B -> A回溯到A，因此A对C而言是可达的——这就是"沿C的祖先路径回溯"的含义。

现在，若从C处切出一个feature-branch，在其上提交D、E，然后切回main提交F，历史图变为：

此时：B对F可达（F -> C -> B），B对E也可达（E -> D -> C -> B）。但无论从F沿哪条父提交路径回溯，都无法到达E或D——因为F的父提交链上根本没有指向它们的分叉。于是我们说：E和D相对F是不可达的。

值得注意的是，"不可达"是一个相对概念：E、D只是相对F（即main分支的当前尖端）不可达，它们仍然是feature-branch尖端E的祖先。判断标准始终是"能否通过祖先路径到达"。

Git 命令如何利用祖先路径：以 git diff 为例

许多 Git 命令依赖祖先路径来决定"显示什么"，git diff就是最典型的例子。git diff用于查看两个提交之间的变更，且不包含起点提交本身。

以上一小节的图为例：

• 执行git diff A..C，得到的是C到A祖先路径（C -> B -> A）上各提交带来的变更，即你会看到B和C的变更。
• 执行git diff B..F，得到的是从F可达路径（F -> C -> B）上的变更，也就是F和C的变更；E和D的变更不会出现，因为它们对F不可达。

这正是"Git 命令使用祖先路径"的直接体现：diff 的边界不是由"时间先后"或"分支归属"决定的，而是由提交图上的可达性决定的。

补充说明..与...的区别，有助于避免常见误用：git diff A..C比较的是两个端点提交本身（等价于git diff A C），其实际含义是"比较A与C两棵树的差异"；而git diff A...C才会使用合并基点（merge-base）。GitHub Desktop 的提交范围 diff 正是基于..语义（详见下文源码剖析），理解这一点才能准确预期"会看到哪些变更"。

合并提交：把不可达变成可达的关键节点

现在把feature-branch合并进main：

合并后，E、D相对F仍然不可达（F的祖先路径没有变化）。但你会自然地想："我把feature-branch合并进了main，应该能看到E、D的变更了吧？"——只有当起点是一个把两条祖先路径都包含进来的提交时，这个想法才成立。这个起点就是合并生成的提交G。

G被称为合并提交（merge commit），它特殊在拥有两个父提交：第一个父提交是合并目标分支（main）的最后提交F，第二个父提交是被合并分支（feature-branch）的最后提交E。于是，图中所有提交都成了G的祖先。

此时执行git diff B..G，会得到G到B的所有祖先路径上的变更：

• 路径一：G -> F -> C -> B
• 路径二：G -> E -> D -> C -> B

因此你会看到G、F、E、D、C全部五个提交的变更——E、D通过第二条祖先路径"重新回到了 diff 的视野中"。这正是合并提交在可达性分析中的核心意义：它把原本分叉的祖先路径收拢成一个节点。

GitHub Desktop 中的表现：线性历史与范围选择 Diff

与git log --graph不同，GitHub Desktop 的 History 界面把提交按时间倒序线性排列展示（最新在最上），不绘制分叉图形。上面"合并提交"一节的历史在 GitHub Desktop 中显示为：

正因如此，界面看起来像一条笔直的提交链，容易让用户误以为从任意一段连续选择中都能看到"全部"变更。

GitHub Desktop 对多提交的 diff 通过**范围选择（range selection）**实现：用户选中连续的一段提交后，应用执行git diff比较选择中第一个与最后一个提交（两端包含），从而显示这段范围内祖先路径上的变更。于是问题出现了：在存在合并提交的分支上做范围选择，被选中的线性区间里可能夹杂着"相对该范围端点不可达"的提交，这些提交的变更不会出现在 diff 中。

下面的动图完整复现了上述"合并提交"场景：在main分支上选中从B到G（含合并提交G）的连续区间后，Readme.md的 diff 中能看到D、E、F、G的变更行，正是G的双亲路径把它们全部收拢进来的结果：

源码剖析：GitHub Desktop 如何实现范围选择 Diff

GitHub Desktop 的多提交 diff 逻辑并不在 UI 层完成，而是封装在app/src/lib/git/diff.ts中，由app/src/lib/stores/app-store.ts调度。理解这两处源码，就能从实现层面印证上文全部概念。

1.getCommitRangeDiff：firstSha^..lastSha 的 rev range 语义

getCommitRangeDiff 是范围 diff 的核心实现。它接收按历史顺序排列的提交 SHA 列表，构造的 git 参数为：

const oldestCommit = useNullTreeSHA ? NullTreeSHA : commits[0] const oldestCommitRef = useNullTreeSHA ? NullTreeSHA : `${commits[0]}^` const latestCommit = commits.at(-1) ?? '' const args = [ 'diff', oldestCommitRef, latestCommit, ... ]

也就是说，实际执行的命令等价于：

git diff <第一个提交>^ <最后一个提交>

即 rev rangefirstSha^..lastSha：以"第一个提交的父提交"为左边界（^表示父提交），以"最后一个提交"为右边界，比较两棵树的差异。这正好对应文档中git diff B..G的行为——B的父提交A作为起点被排除，B之后所有从G可达的祖先路径（G -> F -> C -> B与G -> E -> D -> C -> B）上的变更都被纳入。

代码中有一个重要的边界处理：如果第一个提交是分支的根提交（没有父提交），commits[0]^会解析失败并触发GitError.BadRevision。此时函数会携带useNullTreeSHA = true递归重试，改用NullTreeSHA（空树）作为比较起点，语义变为"从空仓库到这个提交的全部变更"。这一逻辑对应源码注释："This should only happen if the oldest commit does not have a parent (ex: initial commit of a branch) and thereforeSHA^is not a valid reference."。

2.getCommitRangeChangedFiles：同样的 rev range，不同的输出

与getCommitRangeDiff配套的 getCommitRangeChangedFiles 用于获取范围内变更的文件列表（--raw --numstat），其构造的边界与getCommitRangeDiff完全一致（${shas[0]}^与shas.at(-1)），并复用同一套BadRevision -> NullTreeSHA回退策略。在 app-store.ts 中，多提交场景下正是先调用它加载变更文件集，再逐文件调用getCommitRangeDiff渲染具体 diff。

3.getShasInDiff：沿祖先路径找出"真正会出现在 diff 里的提交"

由于 History 列表按时间线性展示，用户选中的一段提交可能横跨两条祖先路径。为此 app-store.ts 的 getShasInDiff 实现了一个沿祖先路径遍历的算法，来精确计算哪些提交的变更会进入 diff：

const shasInDiff = new Set<string>() const selected = new Set(selectedShas) const shasToTraverse = [selectedShas.at(-1)] let sha while ((sha = shasToTraverse.pop()) !== undefined) { if (!shasInDiff.has(sha)) { shasInDiff.add(sha) commitLookup.get(sha)?.parentSHAs?.forEach(parentSha => { if (selected.has(parentSha) && !shasInDiff.has(parentSha)) { shasToTraverse.push(parentSha) } }) } }

它从选区最后一个提交出发，不断把"同时位于选区内的父提交"压入待遍历栈，最终得到的shasInDiff集合就是所有能从右边界沿祖先路径到达且落在选区内的提交——其方法注释明确指出："This is equivalent to doinggit rev-list firstSha^..lastSha."。这个集合一方面用于 UI 上高亮"实际参与 diff 的提交"，另一方面用于触发不可达提交警告。

4. 不可达提交警告：显式提醒"选区中有提交不会出现在 diff 里"

在 app-store 的统计逻辑（app-store.ts）中可以看到，当提交范围跨分支导致部分选中的提交不可达时，应用会给出警告并记录埋点：

const hasUnreachableCommitWarning = !shas.every(s => shasInDiff.includes(s)) if (hasUnreachableCommitWarning) { this.statsStore.increment( 'multiCommitDiffWithUnreachableCommitWarningCount' ) }

即：如果用户选中的 SHA 集合中存在不在shasInDiff中的提交，就判定为"范围内存在不可达提交"，提示用户当前 diff 并未覆盖这些提交的变更。此外源码还区分了multiCommitDiffFromHistoryCount（History 页发起）与multiCommitDiffFromCompareCount（Compare 页发起）两类统计，说明该行为在两种入口下表现一致。

实操总结：如何正确理解与使用提交范围 Diff

• 先看图，再看列表：GitHub Desktop 的 History 是线性时间序，遇到合并提交时要意识到选中区间内可能同时包含两条祖先路径的提交；用git log --graph或提交详情中的父提交信息交叉核对。
• 范围选择 =firstSha^..lastSha：只要区间右端（最后一个提交）不是所有选中提交的祖先，区间内就必然存在不可达提交，其变更不会出现在 diff 中——这是 Git 语义使然，而非软件缺陷。
• 合并提交是"收拢点"：把分叉分支合并进当前分支后，合并提交会成为两条路径的共同祖先，此时以它为右端点的范围 diff 才能完整包含两侧的变更（对应动图中的场景）。
• 留意不可达警告：当 GitHub Desktop 提示选区中存在不可达提交时，若需要看到全部变更，应把选区右端扩展到包含合并提交，或直接比较两个分支（Compare 页的 merge-base 比较）。
• 根提交没有父提交：选择从仓库首个提交开始的范围时，GitHub Desktop 会通过NullTreeSHA（空树）回退处理SHA^失效的情况，所以首个提交的变更也能正确展示。

理解"可达性由祖先路径而非时间顺序决定"这一 Git 核心模型，无论是解读命令行git diff的输出，还是在 GitHub Desktop 中做跨合并提交的范围选择，都能做到心中有图、结果可预期。

延伸阅读

• 原始概念文档：Reachable and Unreachable Commits
• 范围 diff 与范围文件集实现：diff.ts
• 祖先路径遍历与不可达警告：app-store.ts
• Git 相关实现与测试目录、git 单元测试

• 桌面应用
• 版本控制
• 开发工具