Veyra-NRVideo 分支整理实战:把 2.0.0 的 7 个分支收口进 main 的可验证流程
Veyra-NRVideo 分支整理实战:把 2.0.0 的 7 个分支收口进 main 的可验证流程
本文以仓库中的分支整理记录为骨架,完整还原 Veyra-NRVideo 在 2026-10-01 把 2.0.0 全部开发分支合并进本地 main 的全过程:为什么 7 个分支其实指向同一个提交、为什么必须先做 --no-ff 合并再考虑回滚、合并前的存档清单包含哪些可验证产物,以及“哪些分支能删、哪些必须留”的判定标准。读完后你可以照搬这套流程,把任意一个多分支、多 worktree、还带着大量未提交改动的大型仓库安全收口到单主线,并保留一条经 git bundle verify 验证过的回滚路径。
决策背景:收口前的仓库形态
原始记录的开篇就明确了这次操作的性质与边界:
用户决定(2026-10-01):2.0.0 基本没有大问题,先把 2.0.0 各分支整理并合并到
main,存档,更新文档。剩下的小 bug 和功能之后再逐项对。 本记录只描述本地仓库;nrvideo/main仍停在 1.4.4,没有 push,没有 Release。
这短短两句包含了三个关键约束,理解它们是理解后续所有动作的前提:
- 授权范围极窄:只授权了"整理 + 合并进本地
main+ 存档 + 更新文档",没有授权推送,也没有授权发布。远端nrvideo/main仍停在 1.4.4,因此这次合并对任何外部使用者都是不可见的。 - 验收标准是"基本没有大问题",不是"全量回归通过"。记录本身也承认"剩下的小 bug 和功能之后再逐项对",所以这不是一次发布级冻结,而是一次开发主线的形态整理。
- 只描述本地仓库:所有路径(
E:/项目/Veyra/archives/...、C:/Users/123/Desktop/...)都是开发者本机路径,不是仓库内路径。这一点在阅读下文所有表格时必须记住:这些目录不在 Git 里,属于本机产物区。
同一仓库后续的执行记录(项目整理执行记录)把这类本机产物区的统一约定写得更清楚:新构建、下载、日志、测试、解压、临时和打包产物统一放 E:/项目/Veyra/{build,tests,logs,tmp,downloads,deps,test-packages,releases,verify,reports,archives,worktrees} 对应任务目录,源码与受控脚本/文档留在 Git 里。分支存档落在 archives/,正是这条产品纪律的延伸。
结论先行:7 个分支其实是同一个提交
原始记录的第 1 节给出了四条结论,这是整篇文章的技术核心:
- 2.0.0 的 7 个分支全部指向同一个提交
53a2d31(chore(ui-mig): close scope guard integrity loop),没有任何分支独有的提交。这几个名字只是不同阶段留下的指针,不是 7 条并行的开发线。 main是它们的直接祖先(落后 63 个提交、没有分叉),所以合并没有冲突。- 但 P0 之后到 2026-09-30 的全部工作(Codex 与 Claude Code 的 P1–P5、反馈修复、延迟优化)从未提交,一直是 E 盘工作区里的未提交改动。这次一并提交为两个提交(源码/测试/脚本;文档),再合并进
main。 - 合并用
--no-ff,main上有一个明确的「2.0.0 合并」提交;需要整体撤销时可以git revert -m 1。
这里最容易被误读的一点是:"7 个分支"≠"7 条开发线"。在 Git 里,分支只是一个指向提交的可移动标签,两个分支指向同一个 SHA 时,它们的内容完全相同。把 7 个阶段性命名(P0/P1、P2 NR、P3 后端、P4 功能、UI-QML 迁移、字段问题、FG/FSR/XeSS)都留在仓库里,只会让后来者误以为还有 7 个未完成的工作面。
53a2d31 的完整提交号在 UI 迁移主计划 与 UI 迁移恢复计划 中可以交叉验证为 53a2d31c6b34f74b7b6d2953ee2caaec63d44e1d,该文件同时记录了合并前的 main 起点是 df41580f7fa0d2b26718f355640470e8cb94b324。
如何自己复现这三个判断
这三个结论都不是"看一眼觉得像",而是可以用三条命令客观验证的。在任何检出该仓库的机器上:
# 1) 7 个分支是否真的指向同一提交
git for-each-ref --format='%(objectname:short) %(refname:short)' refs/heads | sort
# 2) main 是否为分支的直接祖先,以及落后多少个提交
git merge-base --is-ancestor main codex/p2-nr-20260927; echo "ancestor? exit=$?"
git rev-list --count main..codex/p2-nr-20260927 # 分支独有的提交数
# 3) 有没有分叉:两边的差异提交总数
git rev-list --count --left-right main...codex/p2-nr-20260927
第 2 组的关键在于 git rev-list --count main..<branch>:如果返回 0,说明该分支没有任何 main 之外的内容,删除分支名不丢任何提交;如果 git merge-base --is-ancestor 返回 0,说明它已经是 main 的祖先,合并它是空操作。原始记录说"落后 63 个提交、没有分叉",对应的正是 main..branch = 0 而 branch..main = 63 这种形态。
第 3 条命令输出形如 63 0,左数字是 main 独有的提交数,右数字是分支独有的提交数。右侧为 0 就是"可以直接删"的充分条件——这也是后文判断 55 个旧分支可以随时清理的技术依据。
未提交工作的处置:两次提交 + 无冲突合并
这次整理里真正有"内容"的部分不是那 7 个分支,而是从没进过 Git 的那批改动。
原始记录写得很直白:P0 之后到 2026-09-30 的全部工作(Codex 与 Claude Code 的 P1–P5、反馈修复、延迟优化)从未提交,一直是 E 盘工作区里的未提交改动。这意味着如果直接 git checkout main 或者删掉分支,这批工作就会以最危险的方式留在工作区里——既不在任何提交中,也没有任何引用保护。
处置方式是拆成两个提交:
| 提交内容 | 目的 |
|---|---|
| 源码 / 测试 / 脚本 | 让产品实现进入可追溯历史 |
| 文档 | 让计划、报告、状态记录与代码提交分离,便于后续审查与回滚 |
这种"代码与文档分开提交"的拆分并非形式主义。仓库在后续多次整合中都遵循同样的审查习惯:提交前检查 diff、相关构建和回归,不以接口桩、成功计数、仅编译通过来声称功能通过(见 AGENTS.md 的交付与续接章节)。代码提交与文档提交分开,可以让审查者先看"改了什么行为",再看"写下了什么结论",避免两者互相稀释。
为什么必须 --no-ff
main 是分支的直接祖先,理论上一次快进(--ff-only)就能完成。原始记录却明确选择 --no-ff,理由也写在同一句里:"main 上有一个明确的「2.0.0 合并」提交;需要整体撤销时可以 git revert -m 1"。
这两点值得展开:
- 快进合并不产生提交,历史会变成一条直线,事后无法一眼看出"2.0.0 是从哪里、在哪一天整体进来的"。而
--no-ff会产生一个双亲合并提交,第一父提交是main的原尖端,第二父提交是被合并的分支尖端。 git revert -m 1依赖这个双亲结构。-m 1的意思是"以第 1 个父提交为主线",即撤销合并带来的全部差异、回到main合并前的状态。如果当年用的是快进合并,就没有合并提交可回退,只能逐个 revert 63 个提交——这在紧急回滚场景下几乎不可行。
对应命令形态如下(<merge-tip> 为合并后的提交):
# 合并:第一父 = 合并前的 main,第二父 = 2.0.0 分支尖
git checkout main
git merge --no-ff codex/field-issues-20260930 -m "merge: 2.0.0 各分支整理并入 main(本地,不 push / 不 Release)"
# 需要整体撤销时
git revert -m 1 <merge-tip>
需要说明一个常被忽略的细节:git revert -m 1 之后,如果再次尝试同样的合并,Git 可能认为"这些改动已经合过了"。这不是 bug,而是 revert 记下了一次反向修改。真实工程中的做法是在 revert 之后、重新合并之前,先 revert 那个 revert,或者从旧尖端新建分支再合。
合并后的自检:树必须完全一致
仓库在后续版本发布中反复使用同一条判据——合并后的 Git 树必须与被验证的源树完全相同。例如 2.0.4 验收记录 记录"合并 Git 树与实测源树完全相同",2.0.7 测试计划 也要求"核对完整 Git 树及旧树/脏文件"。对 2026-10-01 这次合并,等价的自检是:
# 合并前后应无差异(合并提交的树 == 第二父的树)
git diff --stat <merge-tip>^2 <merge-tip>
# 与合并前 main 的差异应等于被并入分支的全部内容
git diff --stat <merge-tip>^1 <merge-tip>
第一条命令的输出为空,说明"合并没有偷偷引入额外修改"(没有解决冲突时的手误编辑);第二条非空,说明 2.0.0 的内容确实进来了。这两条一起看,才是"合并正确"而不是"合并成功"。
合并前存档清单:可验证的回滚底座
原始记录第 2 节给出了完整的存档目录与产物表。这不是简单的 cp -r 备份,而是一套按证据类型分工的存档:
目录:E:/项目/Veyra/archives/merge-2.0.0-20261001/(SHA256SUMS.txt 逐文件校验)
| 文件 | 内容 |
|---|---|
veyra-all-refs-before-merge.bundle |
合并前全部引用(分支、标签、远端跟踪)的完整 git bundle,git bundle verify 通过;可 git clone 或 git fetch 回来 |
refs-before.txt / branch-inventory-before.tsv |
合并前每个引用的 SHA;本地分支按「已在 main / 随本次并入 / 未并入」的分类 |
worktrees-before.txt |
合并前的 worktree 清单 |
eworktree-tracked-changes.patch / eworktree-untracked/ / eworktree-status-before.txt |
E 盘工作区提交前的未提交状态(已跟踪文件补丁 + 未跟踪文件原件) |
desktop-tracked-changes.patch / desktop-untracked/ / desktop-status-before.txt |
桌面原目录(C:/Users/123/Desktop/Veyra DLSS Video Player)合并前的未提交状态 |
这套清单的设计逻辑值得逐项拆解,因为它精准对应了 Git 存储模型的四层结构:
- 第一层:引用的名字与指向。
refs-before.txt记录每个 ref 的 SHA,branch-inventory-before.tsv进一步把本地分支分成三类(已在main/ 随本次并入 / 未并入)。这三个分类直接决定了后续"能删还是不能删"。 - 第二层:可达的提交对象。bundle 保存的是"从这些 ref 可达的全部对象",所以删掉分支名后仍能从 bundle 里完整恢复。注意关键限定词是全部引用——只打包
main就会丢掉那些未并入分支的独有提交。 - 第三层:worktree 的挂载关系。
worktrees-before.txt记录每个工作树检出的分支。worktree 元数据在.git/worktrees/下,不随 bundle 走,所以必须单独留痕。 - 第四层:未提交的工作区状态。这是最容易丢的一层:
git bundle只能打包提交对象,打包不进 index 与未跟踪文件。因此必须额外用git diff导出已跟踪文件的补丁,并把未跟踪文件按原字节复制到*-untracked/目录。
原文在"已跟踪文件补丁 + 未跟踪文件原件"的措辞里其实已经点明了这两类必须分开处理——已跟踪文件可以用 patch 表达(可读、可审、体积小),未跟踪文件没有基线可比,只能存原件。
bundle 的验证与恢复命令
存档的价值取决于它能否被验证和恢复。仓库在 分支与工作树归档 里给出了标准做法:
git bundle verify E:/项目/Veyra/archives/project-maintenance-execution-20261027/source-before.bundle
git fetch E:/项目/Veyra/archives/project-maintenance-execution-20261027/source-before.bundle refs/heads/codex/release-2.1.1-20261027:refs/heads/codex/release-2.1.1-20261027
git bundle verify 会检查包内每个 ref 的完整性、所需对象是否齐备、以及是否依赖仓库外部对象。只有 verify 通过,这个 bundle 才算"可恢复",否则它只是一个文件。对 2026-10-01 这次存档,原文明确写了"git bundle verify 通过;可 git clone 或 git fetch 回来",两种恢复语义分别适用于:
git clone <bundle>:把 bundle 当成一个独立仓库完整克隆,适合在另一台机器/另一个目录复现合并前的全貌。git fetch <bundle> <ref>:<ref>:把指定 ref 取回当前仓库,适合"只救回某一个分支"的局部恢复。
同一份归档文档还补了一条重要限制:"不要直接把备份压到现有源树",以及"工作树另用 git worktree add 创建"。原因很实际——把 patch 直接 git apply 到一个已经前进的源码树上,很容易产生误合并;正确做法是先从 bundle 恢复出干净的历史状态,再决定是否需要移植工作区改动。
checkpoint 标签:三个不可变的锚点
原始记录设置了三个标签,构成一条完整的回滚链:
| 标签 | 指向 |
|---|---|
checkpoint/pre-merge-2.0.0-main-20261001 |
合并前的 main(df41580,1.4.4 发布后的文档修正提交) |
checkpoint/2.0.0-branch-tip-20261001 |
提交后的 2.0.0 分支尖(合并的第二父提交) |
checkpoint/merged-2.0.0-20261001 |
合并后的 main |
这三个标签的命名与分工非常讲究:
pre-merge让"合并前那一刻"永远可达。即使日后main前进了几百个提交、E 盘存档被清理,也能一条git checkout checkpoint/pre-merge-2.0.0-main-20261001回到原点。2.0.0-branch-tip是合并的第二父提交。它把"被并入的那批内容"本身也钉住,方便对比"合并前后的差异到底是什么",而不必依赖^2语法(一旦历史被改写,^2就不稳定了)。merged-2.0.0是合并完成点,方便复现"2.0.0 刚合进来时的main"。
标签用 checkpoint/ 前缀而不是 v* 或日期裸名,是因为仓库把 v* 留给正式发行标签(如 v2.1.1、v2.1.1-sources),checkpoint 属于内部锚点。原始记录在最后一节把这条规则正式化:"不再保留'同一提交的多个阶段别名'。阶段点用 checkpoint/* 标签(现有 checkpoint/ui-mig-* 保持不动)。"
2.0.0 分支的去留判定
原始记录第 3 节给出完整的分支处理表:
| 分支 | 处理 |
|---|---|
codex/fg-fsr-xess-20260930 |
已删除(与 main 合并后同一提交,没有独有内容) |
codex/field-issues-20260930 |
保留:E 盘工作区 worktrees/p0-p1-r53-20260927 当前检出在这个分支(本次提交和合并的来源) |
codex/p0-p1-r53-20260927 |
已删除(与 main 合并后同一提交,没有独有内容) |
codex/p2-nr-20260927 |
已删除(与 main 合并后同一提交,没有独有内容) |
codex/p3-node-backend-20260927 |
已删除(与 main 合并后同一提交,没有独有内容) |
codex/p4-functions-20260928 |
已删除(与 main 合并后同一提交,没有独有内容) |
codex/ui-qml-migration-20260925 |
保留:桌面原目录当前检出在这个分支,且有未提交改动 |
并紧跟着写明了恢复方式与后续处置:
删除只删了分支名,提交本身都在
main里;恢复某个名字用git branch <名字> 53a2d31c。这两个保留的分支之后不再使用:桌面目录换到main后即可删除codex/ui-qml-migration-20260925,E 盘工作区用完后即可删除codex/field-issues-20260930。
删除判据的三层逻辑
把这张表和结论段放在一起,可以提炼出一条可复用的判定链:
- 内容是否已在
main(等价性):7 个分支全部指向53a2d31,且该提交已是main的祖先 → 内容没有丢失风险。这是删除的必要条件。 - 是否有工作树正在检出(挂载性):
codex/field-issues-20260930和codex/ui-qml-migration-20260925虽然也满足第 1 条,但仍保留,因为对应的 worktree 正检出在它们上面。删除一个被 worktree 检出的分支,Git 会拒绝(除非强删),强行处理会破坏工作树的一致性。 - 是否有未提交改动(脏状态):
codex/ui-qml-migration-20260925额外带有 50 个修改文件,属于明确的保护对象。
所以"已合入"只是允许删除,不是应该删除。真正的删除动作要等前置条件消失:桌面目录切到 main、E 盘工作区用完。原文用的就是这种"先记录、后清理"的两段式表述,而不是当日一次性清空。
为什么"删名字"几乎无收益,"删检出"才有
记录里有一句容易被跳过的经验总结:「原分支名字本身几乎不占空间,收益主要来自检出副本和它们的构建/运行目录。」这句话出自 项目整理方案 的第四步,但 10-01 的这次操作已经隐含了同一认知——7 个分支只删了 5 个名字,真正占空间的是 E 盘工作区、桌面目录和那 3 个误生成的构建目录(约 375 MB)。
原因在于 Git 的对象库是内容寻址的:7 个分支指向同一个提交,它们的对象只存一份。分支名本身只是 refs/heads/* 下的一行文本。真正占空间的是每个 worktree 的工作区副本、build/ 目录、以及运行/测试包。这正是后续 归档文档 里"89 个干净工作树已经退休,122 个旧分支的完整 tip 保存在已 verify 的 bundle 中"这条记录的分工依据:分支名进 bundle,工作树进删除清单,脏树保留原位。
不属于 2.0.0 的本地分支:55 个祖先 + 4 个独有提交
第 4 节的标题就点明了范围边界:"其余本地分支(不属于 2.0.0,本次没有动)"。这是一次刻意的收敛——整理只处理 2.0.0 相关的分支,其余保持原样,避免范围蔓延引发不可预期的破坏。
已经在 main 里的 55 个
原文说明:都是 1.x 各阶段的修复/实验/发布分支,提交已经在 main 历史中,分支名只是指针,可以随时删除而不丢任何提交。为免误伤,本次没有删(其中若干还被 worktree 检出)。
名单如下(原样保留,便于按名字核对):
agent/av-scheduling-repair、agent/remoteplay-integration、agent/veyra-v1-loop、checkpoint/color-p1-archive-20260917、codex/5060-presets-subtitles-20260918、codex/5090-capture-fg-20260921、codex/bounded-full-chain-20260922、codex/capture-audio-latency、codex/capture-color-144beta-20260920、codex/capture-decode-latency-20260916、codex/capture-fg-clock-repair-20260914、codex/capture-formats-20260914、codex/capture-ui-sync-20260919、codex/color-tab-p1-20260917、codex/cross-monitor-20260919、codex/dlss-recovery-20260920、codex/export-mkv-d3d11-repair-20260917、codex/fg-backend-switch-20260919、codex/fg-cadence-audit-20260920、codex/fg-independent-repair-20260922、codex/fg-scheduling-repair-20260919、codex/fg-stability-20260921、codex/fg-utilization-20260921、codex/frame-pacing-20260918、codex/framegen-fsr-dolby-20260916、codex/fsr41-nvidia-20260918、codex/gpu-dis-integration、codex/hdr-multichannel、codex/media-codec-compatibility、codex/playback-nr-20260920、codex/post140-field-repair-20260917、codex/processing-metrics-and-app-icon、codex/ps5-decoded-frame-strip、codex/ps5-fg-overload-audio、codex/ps5-reconnect-repair、codex/ps5-sampling-repair、codex/ps5-scheduler-telemetry-decode、codex/ps5-source-quality、codex/ps5-stream-recovery、codex/release-1.0.0、codex/release-1.0.1、codex/release-1.0.2、codex/release-1.1.0、codex/release-1.1.1、codex/release-1.3.0、codex/release-p1-repair、codex/rtx30-nr-safe-defaults、codex/screen-capture-20260919、codex/seven-audit-20260919、codex/slider-reset-20260919、codex/smooth-motion-help、codex/subtitle-popup-20260919、codex/user-issues-repair-20260915、codex/video-hdr-20260918、main
(原文用可折叠的 <details> 块包住这份名单,正文里只显示"55 个"这个数字。本文展开列出,方便你按名字逐一核对——这也是这份文档最实用的部分之一。)
从清单可以看出命名规律:codex/<主题>-<日期> 或 codex/<主题>,主题覆盖采集卡格式、帧节奏、FG 稳定性、HDR、PS5 串流、发布准备等。agent/* 前缀用于自动化代理的分支。这种"主题 + 日期"的命名让分支名自带语义,也让 git branch --list 'codex/ps5-*' 这类命令可以直接按功能域筛选。
含独有提交、没有并入 main 的 4 个
| 分支 | 尖端 | 最后提交 | 独有提交数 | 说明 |
|---|---|---|---|---|
codex/avermedia-51-switch-20260917 |
8819ca80 |
2026-09-18 | 1 | AverMedia 诊断的未完成存档(有 worktree out/worktrees/avermedia-51) |
codex/beta-latency-ab-20260918 |
24bc11a3 |
2026-09-18 | 1 | 1.4.2beta 延迟 A/B 探针(有 worktree worktrees/beta-latency-ab-20260918) |
codex/github-source-archive |
2d2a3a6c |
2026-09-08 | 2 | GitHub 源码归档用的分支(对应 origin/main) |
codex/smooth-motion-experiment |
27c17ebb |
2026-09-14 | 1 | Smooth Motion 手工实验(普通版已改为只提供开启说明) |
原文对这一组的处置是明确的:保持原样,是否合并/丢弃需要用户决定。
这 4 个分支的共同特征是"有独有提交",但性质完全不同,不能用同一把尺子量:
- 未完成诊断工具(
avermedia-51-switch):这是排查过程中留下的一次性探针,提交说明本身就是存档标记。它不该作为产品功能合入主线,但也不能直接删——它是那次现场问题的唯一证据链。 - 旧版诊断夹具(
beta-latency-ab):针对 1.4.2beta 的延迟对照测试。记录的次日文档 分支盘点(2026-10-02) 给出了更明确的判断:"main 里的tests/integration/CaptureLatencyComparisonTests.cpp是功能更多的新版"。这说明它不是"遗失的工作",而是"被更好的实现取代的旧工具"。 - 独立历史线(
github-source-archive):对应origin/main的源码快照。02 日的盘点补了一条关键理由:"GitHub 公开仓库的独立历史,和 main 没有共同祖先,不能也不应合并"。没有共同祖先意味着两者无法用普通git merge合并(会因--allow-unrelated-histories之外的原因产生巨量冲突),也不应该合并——那是一条平行的、用于对外发布的历史。 - 已被用户决定取代的实验(
smooth-motion-experiment):02 日盘点说明它"已被 09-14 用户决定取代(只给 NVIDIA App 开启说明),AGENTS.md 要求保留作历史存档"。这是一条典型的"错误方向也要留证"案例:保留的价值不在于代码,而在于记录"为什么当初否掉了这条路"。
这四类正好构成一张判定矩阵,可以直接迁移到别的项目:
| 独有提交的性质 | 处置 | 依据 |
|---|---|---|
| 已被主线更好实现取代的旧工具 | 归档保留,不合入 | 02 日盘点:main 有功能更多的新版 |
| 未完成的诊断/研究探针 | 归档保留,不合入 | 提交说明即存档,不是产品功能 |
| 无共同祖先的独立历史线 | 永不合并,保留 bundle + 固定提交 | 技术上无法合并,语义上不应合并 |
| 用户已明确否决的实验 | 封存,不重新合入 | 决定有日期,恢复需重新授权 |
桌面原目录与 worktree:为什么"不清理"也是结论
第 5 节是全文细节最密集的部分,因为它记录的是没有动的东西及其原因。这类"反向证据"在工程文档里往往比正向操作更有价值。
桌面原目录
- 桌面原目录(
C:/Users/123/Desktop/Veyra DLSS Video Player)仍检出在codex/ui-qml-migration-20260925,本次没有改动它。它有 50 个已修改文件,都是 2026-09-26/27 的旧状态;逐个核对过,对应文件在 E 盘都有更新的版本(E 盘修改时间为 9-27 至 9-30,是在它的快照上继续改出来的),少数几行旧写法被后续重写,没有丢失功能。它另有 3 个误生成的 CMake 构建目录veyra_preset_library_tests/、veyra_qml_easing_tests/、veyra_qml_quick_tests/(约 375 MB,把测试目标名当成了构建目录),是垃圾,未纳入任何提交,也没有删除。- 建议:确认无用后,在桌面目录执行
git checkout main(很可能因为未提交改动被拒绝,先决定这些改动怎么处理;它们的内容已随 E 盘版本进入main,旧状态另存在存档目录里)。
- 建议:确认无用后,在桌面目录执行
这段记录包含三个独立的技术判断,每一个都值得单独理解:
判断一:50 个修改文件为什么可以不处理。 结论不是"猜它们没用",而是"逐个核对过,对应文件在 E 盘都有更新的版本"。判据是文件级对比:E 盘的修改时间(9-27 至 9-30)晚于桌面的快照时间(9-26/27),且 E 盘版本是在桌面快照之上继续改出来的。附加判断是"少数几行旧写法被后续重写"——即便逐文件存在对应关系,也要承认个别行可能被重写成不同形式,因此补一句"没有丢失功能"是结论,而不是假设。
判断二:3 个误生成的构建目录是什么。 veyra_preset_library_tests/、veyra_qml_easing_tests/、veyra_qml_quick_tests/ 这些名字是 CMake 测试目标名,却被当成了构建目录名。这是典型的脚本参数误用:把 -t <target> 或 --target 的值传给了 -B <build-dir>。三个目录合计约 375 MB,全部是可用源码重建的产物,因此"未纳入任何提交,也没有删除"——不提交是避免污染仓库,不删除是因为清理动作需要单独授权与核对。
判断三:git checkout main 为什么会被拒绝。 当工作区有未提交改动,且这些改动会被目标分支的检出覆盖时,Git 会拒绝切换并报错("Your local changes would be overwritten by checkout")。原文的建议很克制:"先决定这些改动怎么处理"。给出了两条出路:改动内容已随 E 盘版本进入 main(可以丢弃)、旧状态另存在存档目录(可以追溯)。这个"先定策略再执行"的顺序,正是避免 git checkout --force 这类危险操作的护栏。
worktree 清单
- 本次一个都没删:
E:/项目/Veyra/worktrees/下 10 个,加桌面out/下 2 个和C:/Users/123/.codex/worktrees/下 1 个,见worktrees-before.txt。p0-p1-r53-20260927:本次的工作区。- 不要清理:
beta-latency-ab-20260918和桌面out/worktrees/avermedia-51,它们检出的正是 §4 里含独有提交的分支。 - 检出的分支已在
main(清理只是删目录,不丢提交):playback-nr-20260920、fg-independent-repair-20260922、fsr41-nvidia-20260918、frame-pacing-20260918、video-hdr-20260918。 - 分离头的对照副本:
v140-fg-compare-20260921、xess143-compare-20260921-r1、dlss-recovery-baseline-20260920,以及桌面out/owner-baseline、.codex/worktrees/p0-p1-r53-20260927(Codex 的)。 - 是否清理由用户决定。
13 个 worktree 被分成四类,这个分类本身就是一个可复用的 worktree 清理决策树:
| 类别 | 例子 | 能否清理 | 原因 |
|---|---|---|---|
| 本次施工树 | p0-p1-r53-20260927 |
否(操作进行中) | 正在提交与合并 |
| 检出未合并分支 | beta-latency-ab-20260918、out/worktrees/avermedia-51 |
绝对不能 | 删除目录后,该分支失去唯一的工作区入口,未完成工作的上下文会散失 |
检出已合入 main 的分支 |
playback-nr-20260920、fsr41-nvidia-20260918 等 5 个 |
可以(只丢目录) | 提交已在 main,目录可随时用 git worktree add 重建 |
| 分离头(detached HEAD)对照副本 | v140-fg-compare-20260921、xess143-compare-20260921-r1、dlss-recovery-baseline-20260920、out/owner-baseline |
谨慎 | 分离头没有分支名保护,清理后只能靠 SHA 恢复 |
第三类的"可以清理"有一个常被忽略的前提:清理只是删目录,不丢提交。这句话只有在"分支已在 main"成立时才对。如果误删了第二类目录,虽然提交还在(分支名指向它),但那个 worktree 里可能存在的未提交改动会永久消失——这正是原文把"不要清理"单独加粗的原因。
第四类的分离头尤其危险。分离头状态下 HEAD 直接指向某个提交,没有分支名做引用。如果该提交同时不被任何分支/标签引用,它会进入"不可达"状态,最终被 git gc 回收。所以对照副本的保护方式不是"别删目录",而是"确认该 SHA 另有引用"——这也是后文建议用 checkpoint/* 标签管理阶段点的深层理由。
之后的用法:main 单主线 + 短命分支 + checkpoint 标签
第 6 节把这次整理沉淀为长期规则,只有三行,但每行都是一条可执行的纪律:
main是唯一主线。以后 2.0.0 的小 bug 和功能,各自从main开一个短命分支(如codex/fix-xxx-日期),验收后合回main并删掉分支名。- 不再保留"同一提交的多个阶段别名"。阶段点用
checkpoint/*标签(现有checkpoint/ui-mig-*保持不动)。 - push、GitHub Release、Runtime Pack 上传仍需在对话中单独授权。
规则一:短命分支解决的是"阶段性别名"问题
这次整理的根本病因不是分支太多,而是同一个提交被起了 7 个阶段名。codex/p2-nr-20260927、codex/p3-node-backend-20260927、codex/p4-functions-20260928 这些名字暗示"还有三条工作线在进行",实际内容全部在 53a2d31 里。
短命分支的约束点在于"从 main 开"和"验收后删名字"这两端。中间的自由度很大(可以随便提交、随便重写),但两端必须干净:起点是当前 main,终点是合并后消失。这让分支列表始终近似等于"正在进行的工作数",而不是"历史上做过的工作数"。
规则二:checkpoint 标签替代阶段别名
把"阶段点"从分支迁移到标签,是这次整理最重要的结构性改进。区别在于:
- 分支名会被移动(新提交推进时),标签不会。
- 分支名出现在
git branch列表里,与"当前工作"混在一起;标签需要git tag -l或git describe才看到。 - 分支名会被误认为"待办",标签天然表达"历史锚点"。
这条规则在后续版本中被反复执行。例如 2026-11-05 本地 main 整合 同样先打了 checkpoint/pre-main-integration-20261105,再在 codex/integrate-completed-20261105 上验证,最后快进 main。这是同一条流程的第二次应用:存档标签 → 集成分支验证 → 主线推进 → 清理冗余分支名。
规则三:授权是分级的
"push、GitHub Release、Runtime Pack 上传仍需在对话中单独授权"这句话划出了三个独立的授权级别:
| 动作 | 影响范围 | 是否可逆 |
|---|---|---|
| 本地 merge | 仅本机 .git |
可(git revert -m 1、checkpoint 标签、bundle) |
git push |
远端分支历史 | 难(已推送的历史被他人拉取后无法真正撤回) |
| GitHub Release | 对外发布产物与标签 | 很难(下载链接、校验值已被记录) |
| Runtime Pack 上传 | 分发运行时组件 | 很难(涉及第三方组件的分发与许可) |
本地合并具备完整回滚路径(存档 + 标签 + --no-ff 合并提交),所以可以一次授权完成;而推送之后,即使强推远端,也已无法收回他人已克隆的副本。这就是为什么原始记录在开头就把"没有 push,没有 Release"作为并列的两条边界写出来,而不是在末尾顺带提一句。
这套流程在后续版本里的复用
2026-10-01 的记录不是孤例。同仓库在之后一个月里反复应用同一套"存档 → 分类 → 合并 → 标签 → 清理"流程,可以对照着读:
2026-10-02:分支盘点接续
分支盘点(2026-10-02) 开门见山:"接 BRANCH_MAP_2026-10-01.md。用户要求「把各分支内容整理好,合并到 main」。"次日 main 前进到 6360b62,并列出了 5 个新合并提交(Xbox/Moonlight 串流、导出页、悬停提示、导出与 GPU 监控修复、i18n)。同时给出了更新后的统计:"本地 68 个分支里 63 个已完整并入 main(分支名只是旧指针,内容都在 main 里)"。
两天对比可见 main 从 df41580(+63 提交)走到 6360b62(+5 个合并提交),并且"已在 main"的分支数从 55 增加到 63。这说明 10-01 定下的规则(短命分支、验收后合并并删名)确实被执行了。
2026-10-27:从"整理"升级为"归档工程"
项目整理方案 面对的规模已经完全不同:本地分支 132 个(其中 121 是 main 祖先,11 不是)、工作树 101 个(有未提交状态的 6 个、合计 516 条状态记录)、Git 标签 461 个。方案第 4 节把 11 个未合入分支逐一分类处置,其分类逻辑与 10-01 的 4 分支表完全同构:已等价纳入、历史计划、文章交付记录、未完成诊断工具、早期计划、旧版诊断夹具、待折叠文档纠偏、独立源码线、暂停保留(Lecram 两条)、已撤回实验。
执行记录 给出了实际动作与量化结果:
- 保存全部 609 引用、101 工作树状态;6 个脏树 516 条状态原始字节 ZIP 逐条 SHA 核验;
source-before.bundle已 verify 并覆盖全部原引用。 - 退休产物证据 ZIP 341,177,909 字节,保存 12,160 份文件并逐 SHA 验证;复核 54,827 文件身份/mtime/size 后删除 43 目录,E 卷空闲增加 24,123,240,448 字节。
retire_native.ps1先核对 bundle 各 tip、实际 HEAD/工作树状态和 ignored 清单,移除 89 个 E 盘干净工作树,122 个旧分支引用退休到 bundle。- 带独有忽略内容的 C 盘树、6 脏树、Lecram 两线和 Codex 托管的脱离分支树保留;发行标签和远端 refs 不动。
分支与工作树归档 是这份工作的索引页,明文写着"122 个旧分支的完整 tip 保存在下表及已 verify 的 bundle 中,89 个干净工作树已经退休。远端分支和发行标签没有删除。"并给出了逐分支的 完整 tip SHA 与 原先是否为 main 祖先 两列——这正是 10-01 那套"引用 + 分类"方法在 122 个分支规模上的直接放大。
值得注意的是执行记录里的一条失败经验:"首次准备检查发现六个旧构建内有 runtime junction,拒绝按普通目录处理;已改为记录链接目标、剪枝不遍历。执行时只删除已验证的链接入口,绝不递归其目标。" 这与 10-01 中"3 个误生成的 CMake 构建目录…没有删除"是同一类警惕:在 Windows 环境下,junction/symlink 会让"看起来是目录"的东西实际指向别处,递归删除可能清空父项目甚至磁盘其他位置。方案文档也提醒过"扫描时跳过 junction/symlink"。
2026-11-05:同一套流程的常规化
2026-11-05 本地 main 整合与分支整理 展示了"轻量版":合并前 main 为 8eda262f...,先打 checkpoint/pre-main-integration-20261105,在 codex/integrate-completed-20261105 上验证(19 个构建目标 134.4 秒通过),再快进 main。清理原则写得很清楚:
已合并且没有被任何工作树检出的冗余本地分支用
git branch -d清理;不强删未合并工作。检查中的工作树分支继续保留,并明确它们已经合入、不是下一步待办。
这里的两个细节值得注意:用 -d 而不是 -D,因为 git branch -d 会在分支未完全合并时拒绝执行,等于让 Git 帮你做最后一道安全检查;以及**"明确它们已经合入、不是下一步待办"**——这是文档层面的防误读措施,对应 当前状态 页首那句"以下带日期的'未提交/未合入'等描述是当时状态"。
命令速查表
把全文出现的动作整理成一份可以直接照抄的清单。所有命令都在仓库根目录执行,<...> 为需替换的占位符。
盘点与判定
# 列出全部分支及其尖端
git for-each-ref --format='%(objectname:short) %(refname:short)' refs/heads
# 判断某分支是否已是 main 祖先(exit 0 = 是)
git merge-base --is-ancestor main <branch>
# 某分支独有的提交数(0 = 可安全删名)
git rev-list --count main..<branch>
# 双向差异(左 = main 独有,右 = 分支独有)
git rev-list --count --left-right main...<branch>
# 某提交被哪些分支/标签引用(判断是否"孤悬")
git branch -a --contains <sha>; git tag --contains <sha>
# 全部 worktree 及其检出状态
git worktree list
存档
# 打包全部引用(分支、标签、远端跟踪)
git bundle create <archive>/all-refs-before.bundle --all
# 必须验证,通过才算可恢复
git bundle verify <archive>/all-refs-before.bundle
# 已跟踪文件的未提交改动
git diff > <archive>/tracked-changes.patch
git diff --cached > <archive>/index-changes.patch
# 未跟踪文件清单(原件另行按原字节复制)
git ls-files --others --exclude-standard > <archive>/untracked-list.txt
# 每个引用的 SHA 快照
git show-ref > <archive>/refs-before.txt
合并与回滚
# 无冲突的 no-ff 合并,保留双亲结构
git merge --no-ff <branch> -m "merge: <说明>"
# 合并后自检:树一致、差异符合预期
git diff --stat <merge>^2 <merge> # 应为空
git diff --stat <merge>^1 <merge> # 应为被并入的全部内容
# 整体撤销(第一父为主线)
git revert -m 1 <merge>
# 用标签钉住三个关键点
git tag checkpoint/pre-merge-<date> <old-main>
git tag checkpoint/<ver>-branch-tip-<date> <branch-tip>
git tag checkpoint/merged-<ver>-<date> <merge>
恢复与清理
# 从 bundle 取回某个分支
git fetch <archive>/all-refs-before.bundle refs/heads/<name>:refs/heads/<name>
# 恢复已删除的分支名(提交仍在 main 中)
git branch <name> 53a2d31c
# 安全删除(未完全合并时会被拒绝)
git branch -d <name>
# 移除工作树(脏状态会被拒绝,不要用 --force 绕过)
git worktree remove <path>
事实边界与已知限制
按照仓库一贯的记录纪律,本文对每条结论标注依据与边界:
可作为事实的内容:分支数量、提交号、分支名、存档文件名、标签名、处置决定、50 个修改文件、3 个约 375 MB 的误生成目录、13 个 worktree 的分类,均来自 分支整理与 2.0.0 合并记录 原文。后续规模数据(132 分支、101 工作树、516 条状态记录、122 分支退休、89 工作树移除、43 目录删除、24,123,240,448 字节释放)来自 项目整理方案 与 执行记录。
本文的补充解释属于推断:文中关于"git rev-list --count main..<branch> 返回 0 即等价于无独有内容"、"--no-ff 的双亲结构是 -m 1 的前提"、"分离头副本的 SHA 可能被 git gc 回收"、"三个构建目录名源自把 CMake 测试目标名当成了构建目录"等说明,是对 Git 与 CMake 通用行为的解释,用于帮助理解原记录的做法,原文并未逐条展开论证。
当前检出的局限:本仓库工作副本是一个快照形态,当前 HEAD 只有单个提交、没有本地分支与标签、远端只有 origin/main。因此文中所有分支、标签、bundle 都无法在当前检出中直接验证,需要回到原始开发环境或从存档 bundle 恢复后才能复现。原文引用的 E:/项目/Veyra/archives/...、C:/Users/123/Desktop/... 等路径是开发者本机路径,不在版本库内。
明确的未验证边界:原始记录没有声明这次合并做过发布级全量回归(原文措辞是"2.0.0 基本没有大问题"、"剩下的小 bug 和功能之后再逐项对");也没有声明远端状态发生变化(明确写了"nrvideo/main 仍停在 1.4.4,没有 push,没有 Release")。任何把这次操作理解为"2.0.0 已发布"的说法都与记录相悖。
一个仍然开放的项:codex/avermedia-51-switch-20260917、codex/beta-latency-ab-20260918、codex/github-source-archive、codex/smooth-motion-experiment 这 4 个含独有提交的分支,原文写的是"是否合并/丢弃需要用户决定"。10-02 的盘点补上了各自不并入的理由,10-27 的方案又给出了逐项处置建议,但截至那份记录,它们仍以归档形态保留——这是有意的"未完成",而不是遗漏。