Skip to content

案例:一次 worktree 认错主线,最后把系统打瘫的事故 ​

一个目录名字里写着 main,我们就把它当成主线。这个看似很小的判断,后来把旧代码、功能分支和未提交改动混在一起,最终影响了线上业务。

事故结果 ​

结果很直接:

  1. 下单无法使用。
  2. 后台系统出现大量回退。
  3. 整个系统几乎全部瘫痪。

事情是怎么开始的 ​

现场有一个目录叫:

text
/private/tmp/imaging-issue-21-main

但它实际检出的分支是旧的本地 main,提交是 92743ab,比 GitHub 上现在的 origin/main 少了 81 个提交。

还有一个目录叫:

text
/private/tmp/imaging-issue-19-main

它实际也不是 main,而是 feat/issue-19-ops-config-main。

真正的功能工作区则是:

text
/Volumes/Luochen/Business-work/Imaging-OnlineRetouchingOrder

它实际检出的是 feat/issue-19-ops-config。这是功能分支,不是主线。它虽然有自己的功能提交,但不能代替最新的 main。

问题就从这里开始了:大家以为自己在处理主线,实际上每个人手里的代码可能来自不同分支、不同时间点。

从 GitHub 页面看这几个分支 ​

下面这张截图是 GitHub 的远端分支页面。它能告诉我们 GitHub 上有哪些分支、每个分支和 main 相差多少提交,以及有没有关联 PR。

GitHub 分支列表截图

但它看不到电脑里的 worktree,也看不到某个目录里有没有没提交的文件。这两件事必须分开看。

截图里有一个默认分支和五个个人分支。Your branches 和 Active branches 只是同一批分支的两种展示,不是多出来的分支。

分支人话解释截图里的状态
mainGitHub 上的默认主线其他分支通常拿它来比较
feat/issue-19-ops-configIssue 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 仍然把它记成了可以清理的对象。

worktree 只读审计截图

这张图不是为了证明“已经清理完了”,而是为了在清理之前留下证据:哪些目录还在、各自是什么分支、哪些目录有改动、哪个目录已经找不到了。

后来应该怎么做 ​

第一,先认清楚主线。以 GitHub 上最新的 main 为准,不以目录名字和电脑里旧的 main 为准。

第二,把每个任务、分支和 worktree 一一对应起来。一个目录到底服务哪个任务,必须说得清楚。

第三,功能分支要一项一项合回主线,遇到冲突就逐个文件确认,不能为了快直接覆盖整个目录。

第四,没提交的改动要单独登记和保存,不能默认它们已经在某个分支里。

第五,worktree 可以在任务完成后删除,但删除必须是最后一步。只有代码已经提交、推送、PR 和验收材料已经交接,未跟踪文件也确认处理完,才允许删。

以后怎么判断真的完成了 ​

开始任务前,要留下主线版本、任务和分支的对应关系,以及每个 worktree 当时有没有改动。

任务结束时,要确认代码已经保存、已经推送、PR 结果明确,截图和测试材料也已经交接。只要还有一项说不清,就不能清理 worktree。

复盘结论 ​

这次事故不是某条 Git 命令敲错了,而是几个本来应该分开的身份被混成了一件事:

  • GitHub 的 main,是远端主线。
  • 功能分支,是某一项工作的路线。
  • worktree,是电脑里的工作目录。
  • PR,是远端审核记录。

它们必须互相对应,但不能互相冒充。

真正应该记住的一句话是:

先确认主线,再确认分支;先保护现场,再恢复代码;最后一步,才是清理 worktree。

从 Demo 到商用:用 AI 编程,把 Demo 做成能收钱、能长期运行的项目。