案例:一次 worktree 认错主线,最后把系统打瘫的事故
一个目录名字里写着 main,我们就把它当成主线。这个看似很小的判断,后来把旧代码、功能分支和未提交改动混在一起,最终影响了线上业务。
事故结果
结果很直接:
- 下单无法使用。
- 后台系统出现大量回退。
- 整个系统几乎全部瘫痪。
事情是怎么开始的
现场有一个目录叫:
/private/tmp/imaging-issue-21-main但它实际检出的分支是旧的本地 main,提交是 92743ab,比 GitHub 上现在的 origin/main 少了 81 个提交。
还有一个目录叫:
/private/tmp/imaging-issue-19-main它实际也不是 main,而是 feat/issue-19-ops-config-main。
真正的功能工作区则是:
/Volumes/Luochen/Business-work/Imaging-OnlineRetouchingOrder它实际检出的是 feat/issue-19-ops-config。这是功能分支,不是主线。它虽然有自己的功能提交,但不能代替最新的 main。
问题就从这里开始了:大家以为自己在处理主线,实际上每个人手里的代码可能来自不同分支、不同时间点。
从 GitHub 页面看这几个分支
下面这张截图是 GitHub 的远端分支页面。它能告诉我们 GitHub 上有哪些分支、每个分支和 main 相差多少提交,以及有没有关联 PR。

但它看不到电脑里的 worktree,也看不到某个目录里有没有没提交的文件。这两件事必须分开看。
截图里有一个默认分支和五个个人分支。Your branches 和 Active branches 只是同一批分支的两种展示,不是多出来的分支。
| 分支 | 人话解释 | 截图里的状态 |
|---|---|---|
| main | GitHub 上的默认主线 | 其他分支通常拿它来比较 |
| feat/issue-19-ops-config | Issue 19 的功能分支 | 比 main 少 61 个提交,多 22 个提交,已经分叉 |
| fix/refresh-dispatch-test | 刷新派发测试的修复分支 | 比 main 少 3 个提交,但没有自己的新提交 |
| fix/optional-retoucher-leader | 允许没有 leader 的修复分支 | 比 main 少 4 个提交,但没有自己的新提交 |
| fix/order-500-datetime-serialization | 修复订单时间序列化 | 比 main 少 7 个提交,多 1 个自己的提交 |
| fix/remove-order-delay | 删除订单延期流程的修复分支 | 比 main 少 33 个提交,关联 PR #57 |
Behind 可以理解成“这个分支落后主线多少提交”;Ahead 可以理解成“这个分支自己多了多少提交”。
比如 feat/issue-19-ops-config 的 Behind 61 / Ahead 22,不是说它就是 main,而是说它和 main 已经走成了两条路:主线有 61 个它没有的提交,它自己也有 22 个主线没有的提交。
截图里的绿色 3 / 3 只说明检查通过,不说明已经合并。右边的 PR 标记说明 GitHub 找到了关联 PR,也不等于本地 worktree 已经安全。右侧垃圾桶是删除远端分支的入口,在现场没有核对清楚之前不能点。
还有一个前提:私有仓库的保护不是默认免费的
如果仓库是公开的,GitHub Free 就可以给 main 设置分支保护。
如果仓库是个人私有仓库,GitHub Free 不能使用这类完整保护。也就是说,你不能靠免费账户强制要求“必须走 PR、必须审核、必须通过检查后才能合并”。个人私有仓库需要开通 GitHub Pro,目前是每月 4 美元。
如果仓库属于组织,私有仓库通常要看组织是否开通 Team 或 Enterprise。只升级个人账号的 Pro,不一定能替组织仓库打开保护。
所以这次事故的防线有两层:本地要把 worktree 和真实分支对应清楚,GitHub 上还要有能力保护 main。没有付费计划时,只能靠人为约定,GitHub 不会替你拦住直接改 main 的操作。
具体可看 GitHub 官方分支保护说明 和 GitHub 定价。
事故不是一个错误造成的
1. 把目录名字当成了分支
目录叫 imaging-issue-21-main,不代表里面就是主分支。真正要看的,是这个目录当前检出了什么分支。
2. 把电脑里的旧 main 当成了最新主线
本地 main 只是电脑里保存的一份分支。它可能很久没有同步。真正恢复时,要先确认 GitHub 上最新的 main 到底是哪一个提交。
3. 把功能分支当成了主线
功能分支只说明“这里做过某项功能”,不说明它已经包含主线上的所有新变化。功能分支和主线都要保留各自的身份,不能混着叫。
4. 没先保护 worktree 里的改动
一个 worktree 里可能有已经提交的代码,也可能有还没提交的源码、测试、截图、文档和录屏。
如果只看分支,不看目录里真实的文件状态,就不知道哪些东西已经保存,哪些东西还在现场。这个时候一旦覆盖、重置或清理,没进提交记录的内容就可能直接丢掉。
为什么最后会影响业务
错误的主线判断,会让恢复出来的代码缺少主线已经有的改动;错误的分支判断,又可能把还没有正确合并的功能带进来。
如果这时再把 worktree 里没提交的内容覆盖掉,系统就会同时出现“该有的东西没有”和“新旧代码混在一起”两种问题。最终表现出来,就是下单不可用、后台大量回退,整个系统几乎瘫痪。
这也是为什么这次不能把它当成一次普通的 Git 分支整理。它已经变成了业务可用性事故。
复盘时,第一件事不是清理
在真实状态没有盘点清楚之前,先不删除任何东西:
- 不删 worktree。
- 不删分支。
- 不清理未跟踪文件。
- 不重置代码。
- 不用一个目录覆盖另一个目录。
2026-08-23 的只读盘点显示:现场共有 15 个 worktree;功能主工作目录有 14 条未提交改动;恢复目录有 36 条未提交改动;还有一个目录已经不存在,但 Git 仍然把它记成了可以清理的对象。

这张图不是为了证明“已经清理完了”,而是为了在清理之前留下证据:哪些目录还在、各自是什么分支、哪些目录有改动、哪个目录已经找不到了。
后来应该怎么做
第一,先认清楚主线。以 GitHub 上最新的 main 为准,不以目录名字和电脑里旧的 main 为准。
第二,把每个任务、分支和 worktree 一一对应起来。一个目录到底服务哪个任务,必须说得清楚。
第三,功能分支要一项一项合回主线,遇到冲突就逐个文件确认,不能为了快直接覆盖整个目录。
第四,没提交的改动要单独登记和保存,不能默认它们已经在某个分支里。
第五,worktree 可以在任务完成后删除,但删除必须是最后一步。只有代码已经提交、推送、PR 和验收材料已经交接,未跟踪文件也确认处理完,才允许删。
以后怎么判断真的完成了
开始任务前,要留下主线版本、任务和分支的对应关系,以及每个 worktree 当时有没有改动。
任务结束时,要确认代码已经保存、已经推送、PR 结果明确,截图和测试材料也已经交接。只要还有一项说不清,就不能清理 worktree。
复盘结论
这次事故不是某条 Git 命令敲错了,而是几个本来应该分开的身份被混成了一件事:
- GitHub 的 main,是远端主线。
- 功能分支,是某一项工作的路线。
- worktree,是电脑里的工作目录。
- PR,是远端审核记录。
它们必须互相对应,但不能互相冒充。
真正应该记住的一句话是:
先确认主线,再确认分支;先保护现场,再恢复代码;最后一步,才是清理 worktree。