DEVELOPER DESK阅读地图
7个主要章节
1段代码示例
6组图片与图表

先定位当前任务,再对照操作前提、结果与容易混淆的边界。

章节速览7 节 · 展开选择

Git差异审查比较工作区、暂存区与HEAD,回答下一次提交准备保存什么。分支审查还有另一层问题:主分支与功能分支都前进以后,我们想看的是两个当前版本哪里不同,还是功能分支相对共同历史增加了什么?

git diff main topic、git diff main..topic、git diff main...topic外观接近,比较的起点却不相同。更容易混淆的是,git log也使用双点与三点,但它在选择提交集合,不能把它的语义直接搬给文件差异。

本篇用一个明确分叉、唯一最佳共同祖先的小仓库推导这些关系。实验只新建本地教学仓库,保留所有产物,不连接远端,也不操作博客部署仓。

先写两个端点是当前主分支,还是共同祖先?

比较命令之前,先给提交和文件树命名。同一个右端点,换一个左端点就会得到不同补丁。

再核对命令对象文件变化与提交集合分开

diff显示快照之间怎样变化;log选择历史里的哪些提交。标点相同,不代表两者在回答同一个问题。

先画清历史,再给内容命名

设最初提交为A,文件note.txt只有一行base。从A建立功能分支后,主分支增加一行main,形成B;功能分支先增加topic-1形成C,再增加topic-2形成D。当前main指向B,codex/demo-topic指向D。

为了避免把名称当成时间,先记住父关系:B的父提交是A,C的父提交也是A,D的父提交是C。A是两条历史共有的祖先;在本例中,它也是唯一的最佳共同祖先。这里的最佳不是日期最新,而是按提交可达关系比较,见文献2。

A分叉到主分支B和功能分支C、D;双点比较B到D,三点比较A到D
图1|原创教学历史。箭头表示父到子的关系,位置不表示提交耗时。两个比较都以D为右端点,但左端点不同。查看原图
提交所在位置note.txt的有序行
A共同历史base
Bmain当前端点base;main
C功能分支中间提交base;topic-1
D功能分支当前端点base;topic-1;topic-2

表中的分号只是分隔文本行,不是文件里实际写入的字符。先读出这四份快照,后面每一项差异就能直接手算,不必把标点记成抽象口诀。

双点diff仍然是在比较两个端点

git diff main codex/demo-topic询问:把B的文件树变成D的文件树,需要哪些文本变化?本例会移去main这一行,再加入两行topic-1和topic-2。补丁里的减号描述比较方向,不表示命令已经删除文件或修改分支。

官方diff文档明确,提交参数的双点形式与两个独立端点形式同义,见文献1。因此git diff main..codex/demo-topic在这里也比较B与D,而不是先枚举主分支没有的每个提交再分别输出。

比较约定G1|双点diff的左右快照
git diff L R ≡ git diff L..R
比较:tree(L) → tree(R)

L、R在本文均为已解析的提交;tree(X)表示X记录的文件树。箭头是补丁方向,不是时间轴,也不是会被执行的合并。本文命令不包含工作区与暂存区的未提交修改。

自检1:双点补丁出现-main,是否证明功能分支曾经删过这一行?

不能。功能分支从A出发,可能从未拥有这一行。减号只说明左端点B有它、右端点D没有它;必须回到比较端点和历史,才能解释变化的来源。

将方向改为git diff codex/demo-topic main,补丁就会移去两行topic内容、加入main行。快照差异有方向,交换左右端点不是同一个问题。

三点diff把左端点换成共同祖先

git diff main...codex/demo-topic先从两个端点的历史寻找共同祖先,再把这个祖先的文件树与右端点D比较。本例从A到D,所以只增加两行topic内容,不出现-main:A本来就没有main行。

比较约定G2|唯一最佳共同祖先下的三点diff
M = merge-base(L, R)
git diff L...R ≡ git diff M R

本式限定存在唯一最佳共同祖先M,且端点保持不变。它不是将L与R的全部改动相加;只显示M到右端点R的文件树差异。多个最佳共同祖先需要额外检查。

反过来写git diff codex/demo-topic...main,共同祖先仍为A,右端点却成为B,因此只增加main行。这说明三点diff也不是对称比较:它对共同历史的选择对称,对最终显示哪一侧的变化并不对称。

一种有用的审查习惯是,先用日常语言写下问题,再选命令:若要看两个待运行版本的文件树差异,比较端点;若要看分支相对共同历史的净变化,选择合适的三点方向。两者可以一起看,但不应互相代替。

同样的双点与三点,log选择的是提交集合

对这份历史,git log main..codex/demo-topic选择从D可达、但从B不可达的提交,即C和D。git log main...codex/demo-topic选择两侧可达历史的对称差,即B、C、D;共同的A不在其中。集合定义见文献3,这里不约定这几项在日志里出现的顺序。

集合约定G3|log的可达集合
log L..R:Reach(R) ∖ Reach(L)
log L...R:两侧可达集合的对称差

Reach(X)含提交X自身及沿父关系可达的祖先。这里选择的是提交身份,单位是离散提交;不是diff补丁的行数,也不是对补丁求并集。

命令本例在问什么应看到的核心结果
diff main topicB到D的树差异移去main,加入两行topic
diff main..topic仍是B到D与上行相同
diff main...topicA到D只加入两行topic
diff topic...mainA到B只加入main
log main..topic右侧独有可达提交集合C、D
log main...topic两侧可达集合对称差集合B、C、D

表中topic是功能分支的简写,实际实验使用完整名字codex/demo-topic。如果一个分支修改某行后又改回原状,log仍可能选中这两次提交,而端点diff可以为空:提交身份、提交数量和净文件变化并不是同一份信息。

一段可以实际运行的PowerShell实验

下面的代码只在当前目录下建立一个带随机名字的新教学仓库。所有历史都在这一个新目录里;它不设置remote,也不触碰已有仓库。若任意Git命令失败,包装函数立即抛错,不继续把后续输出当成有效结果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
$ErrorActionPreference = 'Stop'
function Invoke-TeachingGit {
& git @args
if ($LASTEXITCODE -ne 0) { throw 'Teaching Git command failed' }
}
$start = (Get-Location).Path
$demo = Join-Path $start ('branch-diff-' + [guid]::NewGuid().ToString('N'))
New-Item -ItemType Directory -Path $demo | Out-Null
try {
Set-Location -LiteralPath $demo
Invoke-TeachingGit init --quiet --initial-branch=main
Invoke-TeachingGit config user.name 'Branch Diff Demo'
Invoke-TeachingGit config user.email 'demo@example.invalid'
Invoke-TeachingGit config core.autocrlf input
Invoke-TeachingGit config gc.auto 0
Invoke-TeachingGit config maintenance.auto false
New-Item -ItemType File -Path 'note.txt' -Value "base`n" | Out-Null
Invoke-TeachingGit add -- note.txt
Invoke-TeachingGit commit --quiet -m A
Invoke-TeachingGit branch codex/demo-topic
Add-Content -LiteralPath 'note.txt' -Value 'main'
Invoke-TeachingGit add -- note.txt
Invoke-TeachingGit commit --quiet -m B
Invoke-TeachingGit switch --quiet codex/demo-topic
Add-Content -LiteralPath 'note.txt' -Value 'topic-1'
Invoke-TeachingGit add -- note.txt
Invoke-TeachingGit commit --quiet -m C
Add-Content -LiteralPath 'note.txt' -Value 'topic-2'
Invoke-TeachingGit add -- note.txt
Invoke-TeachingGit commit --quiet -m D
Write-Output '=== endpoint diff ==='
Invoke-TeachingGit diff main codex/demo-topic -- note.txt
Write-Output '=== two-dot diff ==='
Invoke-TeachingGit diff main..codex/demo-topic -- note.txt
Write-Output '=== three-dot diff ==='
Invoke-TeachingGit diff main...codex/demo-topic -- note.txt
Write-Output '=== reverse three-dot diff ==='
Invoke-TeachingGit diff codex/demo-topic...main -- note.txt
Write-Output '=== right-only commits ==='
Invoke-TeachingGit log --format=%s main..codex/demo-topic
Write-Output '=== symmetric commits ==='
Invoke-TeachingGit log --format=%s main...codex/demo-topic
Write-Output ('Teaching repository: ' + $demo)
} finally {
Set-Location -LiteralPath $start
}

把每段输出与上面的手算表比较,重点看补丁中的内容行,不要把---与+++文件头误算成正文增减。完整提交哈希、运行目录和日志顺序可能不同,不应拿一份固定截图作为唯一正确输出。

三点审查没有替你完成哪些判断

首先,它不证明分支能无冲突合并。主分支与功能分支可能独立改动相邻区域;以共同祖先为起点的补丁只展示一侧净变化,不运行合并算法,更不运行构建、测试或权限检查。

其次,共同祖先不是永远固定的分叉日期。分支如果合入过其他历史,最佳共同祖先可能随提交图改变;长期保存的审查结论应记录当时两端的完整提交身份与采用的比较起点,而不只保存容易继续移动的分支名字。

最后,复杂的交叉合并历史可能有多个互不优于对方的最佳共同祖先。官方merge-base文档说明,不带--all时输出哪一个并无保证。遇到这类图,应先检查所有最佳候选并明确审查规则,不能继续把G2中的M当成天然唯一。

端点差异选B与D,共同历史差异选A与D,独有提交集合选C与D;三类问题分别记录起点、终点或集合
图2|原创问题对照。框宽不表示提交数量、文件大小或审查成本。三点diff与三点log在这里属于不同的对象类型。查看原图
自检2:交换三点diff左右参数,是否只是给原补丁换个正负号?

通常不是。本例正向比较A到D,反向比较A到B,左侧共同祖先不变,但右侧换成了另一条分支。两份补丁展示各自的净变化,不是同一对端点的简单反向。

自检3:log选出了两个独有提交,diff是否一定非空?

不一定。两次修改可以互相抵消,最终文件树回到原状。log保留提交身份,diff比较所选快照;提交集合非空不能推出净文件变化非空。

自检4:三点补丁看起来很小,能据此保证合并后测试通过吗?

不能。比较没有执行集成,更没有验证运行行为。需要另外核对合并条件、候选集成结果与相应测试;小补丁也可能改变关键条件。

参考文献与复查入口

  1. Git:git-diff。 2.41版官方手册。核对双点端点同义、三点共同祖先方向及diff不按提交范围解释的说明。返回G1。
  2. Git:git-merge-base。 官方手册。用于最佳共同祖先、祖先关系与多个最佳候选的边界。返回G2。
  3. Git:gitrevisions,Dotted Range Notations。 提交可达集合与范围。用于log双点与三点的集合语义;教学文件与A至D历史均为本文独立构造。返回G3。