Veyra-NRVideo 分支治理实战:从 68 个本地分支收敛到单线 main 的完整方法与源码依据
Veyra-NRVideo 分支治理实战:从 68 个本地分支收敛到单线 main 的完整方法与源码依据
本文以仓库中的分支盘点记录 BRANCH_MAP_2026-10-02 为主线,完整还原 Veyra-NRVideo 在 2026-10-02 把「各分支内容整理好、合并到 main」这件事的执行方法:五次合并分别带进了什么、68 个本地分支为什么有 63 个可以直接视为已并入、剩下 4 条为什么被有意保留、工作区未提交改动如何定性,以及后续如何用 git merge-base、git cherry、git bundle verify 把这份盘点在任意克隆上复核一遍。文中同时给出每个合并项在仓库源码中的落地位置,便于把「分支治理结论」与「产品实现」对上号。
一、这份盘点的定位与硬边界
盘点开篇就写明了两条边界,理解它们才能正确引用这份文档:
- 它接续 BRANCH_MAP_2026-10-01,属于同一轮「整理分支并合入 main」工作的第二篇记录;
- 它只描述本地仓库:没有
push,没有 Release。
这两条意味着文中的提交哈希是本地历史事实,而不是公开远端状态。对应到当前仓库,执行 git log 只能看到一个提交(该检出为浅克隆,.git/shallow 中记录了唯一提交 d8dd57b),因此 ab1fe96、6360b62 这类短哈希在当前检出里无法用 git cat-file 解析。要逐条核对,需要用完整历史仓库或归档 bundle,这一点在第五节给出操作命令。这是本文刻意标注的证据边界,避免把「文档里的提交号」误当成「当前克隆可验证的对象」。
二、main 现状:五次合并提交逐条拆解
文档给出的 main 基线是 6360b62,在 10-01 之后并入了以下五个合并提交:
| 合并提交 | 分支 | 内容 |
|---|---|---|
ab1fe96 |
codex/xbox-20261001(含 codex/moonlight-20261001) |
PC 串流、Xbox 串流、美乐威低延迟、现场修复第 1–4 批 |
931eade |
codex/export-page-20261002 |
导出页队列、MKV / 多音轨 / 内嵌字幕、取消重试、完成提示音 |
fb47a14 |
codex/tooltip-nr-20261002 |
悬停提示不被画面挡住、列表模式 NR 总开关、beta 7 说明 |
b205d29 |
codex/export-xbox-fixes-20261002(含 codex/gpu-monitor-20261002) |
GPU 占用单卡监控、导出慢帧 / 显卡重置处理、导出默认值、第 6 批 |
6360b62 |
codex/i18n-20261002 |
繁中 / 英 / 日界面语言 |
注意最后一行的 6360b62 既是「并入 i18n 分支」的合并提交,也是文档声明的 main 现状。这种写法在「按时间顺序列合并记录」的文档里很常见:最后一条既是变更也是终点。
下面把每一行对应到仓库中的实际模块,验证这些「内容」不是空泛描述。
2.1 串流与采集:ab1fe96
这一批把三类输入源和现场修复合到一起,仓库中仍能按目录结构对应上:
- Xbox 串流:src/xbox/WebRtcSession.cpp、src/xbox/StreamApi.cpp、src/xbox/Account.cpp;
- PC / Moonlight 串流:src/moonlight/Client.cpp、src/moonlight/Pairing.cpp、src/moonlight/Discovery.cpp;
- 美乐威采集:src/source/MagewellCapture.cpp,其 SDK 许可说明在 licenses/magewell/MWCapture-SDK-NOTICE.txt;
- 会话层封装:src/source/XboxSessionSource.cpp、src/source/MoonlightSessionSource.cpp。
一条分支同时带 xbox 与 moonlight 两个阶段的提交,说明当时是「一条主干分支覆盖同一次输入源改造」,合并时只需一条合并提交,避免拆成两条互相依赖的分支再解决顺序冲突。
2.2 导出页:931eade
这是五个合并里技术密度最高的一项。文档列出四个可验证的能力点:导出页队列、MKV / 多音轨 / 内嵌字幕、取消重试、完成提示音。仓库中对应:
- 队列与状态机:include/veyra/engine/ExportQueue.h 定义了
ExportItemState(Ready / Queued / Running / Done / Failed / Cancelled)与ExportQueueItem(id/batch/job/revision/inspected、progress/start/end、frozen冻结设置、hevc、explicitOutput、码率控制rate)。头文件注释明确该队列是「QML 队列唯一的顺序/状态存储」,而既有 manager 仍是单进程执行器,旧的立即入队 API 在此不使用; - 实现:src/engine/ExportQueue.cpp,对外方法包括
add / remove / clearWaiting / move / retry / setTrim / setTracks / setContainer / start / cancel / tick; - QML 模型桥:src/ui/QmlExportQueueModel.cpp 与 include/veyra/ui/QmlExportQueueModel.h;
- 容器与轨道选择:include/veyra/engine/ExportStreams.h,
setTracks接收ExportTrackSelection,setContainer接收ExportContainer(默认Mp4,见头文件中的container_=ExportContainer::Mp4); - 提示音:
MessageBeep调用点在 src/ui/QmlPlayerBridge_p.h,形如const BOOL queued=enabled?MessageBeep(MB_OK):FALSE;,由偏好开关控制,与文档「默认启用 Windows MessageBeep,可关闭并持久保存」一致; - 测试:tests/unit/ExportQueueTests.cpp 覆盖队列单元行为,tests/integration/ExportWorkflowTests.cpp 覆盖端到端导出。
导出页那一轮的具体验收细节(MKV 音轨包边界、PGS 图片字幕拒绝策略、临时文件隔离等)在同目录的 导出优化执行与验收记录 中,本文不重复展开,但它解释了为什么这条分支值得单独占一个合并提交:改动面横跨引擎、UI 桥和 QML 三层。
2.3 交互与 NR 列表模式:fb47a14
文档写的是三件事:悬停提示不被画面挡住、列表模式 NR 总开关、beta 7 说明。其中「列表模式」与「总开关」在桥接层有明确痕迹:src/ui/bridge/Chain.cpp 中出现 impl_->nrMasterRestore,src/ui/bridge/Preferences.cpp 用 const bool listMode = !active.editor; 区分「列表态」与「编辑器态」,并在列表态下恢复记忆值。这正是「列表模式 NR 总开关」这类需求需要的两段逻辑:总开关的值在两种界面形态之间同步,而编辑器态不覆盖列表态的既有选择。
「悬停提示不被画面挡住」属于纯 UI 层级问题,通常通过调整浮层与视频宿主窗口的 Z 序解决;仓库中视频宿主是独立 HWND,QML 内容层与其分层,这条修复的形态与此吻合。由于我没有在该文档中找到具体实现文件,此处只作结构性说明,不作为已验证结论。
2.4 GPU 单卡监控与导出健壮性:b205d29
这条合并包含两个子分支:codex/export-xbox-fixes-20261002 与 codex/gpu-monitor-20261002。GPU 单卡监控的实现可以直接在 src/ui/bridge/Status.cpp 中读到完整机制:
- 数据源与任务管理器一致:PDH 计数器
\GPU Engine(*)\Utilization Percentage,每秒采样一次,独立线程; - 计数器实例名形如
pid_<n>_luid_0x<high>_0x<low>_phys_..._engtype_<type>,代码从实例名中解析engtype_并按引擎类型(3D、Copy、VideoDecode 等)累加,取「最忙的引擎类型」作为占用率; - 关键的一点是 LUID 过滤:
impl->gpuMonitorLuid.load()非零时,只保留实例名中包含luid_0x........_0x........_的条目。这就是「单卡」的实质——多卡机器上如果不按 LUID 过滤,会把另一块显卡的占用率一起算进来; - 不可用时返回
-1:gpuUtilizationKnown()以>= 0.0判断,UI 据此显示「未知」而不是伪造 0%。
「导出慢帧 / 显卡重置处理」在导出流水线里也有可查证据:src/engine/VideoExportJob.cpp 存在测试钩子 device5->RemoveDevice(),日志打印 removedReason=0x{:X};同文件还实现了基于 fence 的完成事件等待,超时 30 秒会记录 frame GPU completion timed out after 30s,并在事件注册失败时回退到轮询。这类「先试事件、失败退化为轮询」的设计,正是导出在显卡异常或驱动缓慢时不至于永久挂死的工程手段。
2.5 界面语言:6360b62
i18n 的实现边界很清楚,值得单独说明,因为它决定了「繁中 / 英 / 日」是怎么被接进来的:
- 源语言是简体中文:所有 QML
qsTr与 C++tr的字符串本身即查找键,见 include/veyra/ui/UiLanguage.h 头注释; - 词表是编译进可执行文件的 i18n/catalog.json,当前为
entries数组、共 2739 条,每条形如{"zh": ..., "src": "src/ui/bridge/RemotePlay.cpp", "zh-TW": ..., "en": ..., "ja": ...}。src字段保留来源文件,便于反查哪条字符串来自哪个模块; - 语言码集合固定在 src/ui/UiLanguage.cpp:
zh-CN、zh-TW、en、ja;auto或空值按系统语言解析,zh-TW / zh-HK / zh-MO归繁中,其余中文归简中,日文归ja,其他归英文(同文件 160–175 行附近); - 缺词回退为中文源串,这是文档所说「missing entry 显示中文源串」的机制。
这条分支之所以能独立合并,是因为它只改词表与翻译装载层,不动界面结构;这也解释了为什么它排在最后。
三、68 与 63:为什么「分支名只是旧指针」
文档给出的数字是:本地 68 个分支里 63 个已完整并入 main,并明确说明「分支名只是旧指针,内容都在 main 里」。
这里有一个容易误读的地方:后续「没有并入 main 的分支」表只列了 4 条。若把 main 自身也算作一个分支引用,则 63 + 4 + 1 = 68,与开头的 68 完全吻合。这是从文档数字结构推断出的解释,文档本身没有逐条点名这 68 个分支。
「已完整并入」在 Git 里有严格定义:分支 tip 是 main 的祖先。判定命令如下(在完整历史克隆中执行):
# 1) 分支 tip 是否为 main 祖先:返回 0 表示已并入
git merge-base --is-ancestor <tip> main && echo "merged" || echo "not merged"
# 2) 分支相对 main 的独有提交数
git rev-list --count main..<branch>
# 3) 补丁等价性检查(跨 rebase 后仍能识别“内容已进 main”)
git cherry -v main <branch>
# 4) 快速列出所有 tip 已在 main 内的分支名
git branch --merged main
git for-each-ref --format='%(refname:short) %(objectname:short)' refs/heads
为什么这三条要一起用,而不是只看 git branch --merged:
--merged只看提交可达性,遇到「同一改动被 cherry-pick 成不同哈希」会误判为未合并;git cherry比较补丁 ID(patch-id),能识别「内容已存在但哈希不同」,代价是遇到冲突改写或上下文变动时会显示+;rev-list --count给出「独有提交数」,为 0 才是真正的零遗失。
后续的 当前分支归并核对(2026-10-16) 正是把这套方法落到了文字里:核对基线 0cfa8a8c...,89 个本地分支中 84 个 tip 已在 main 祖先链内,且明确写了「以下 tip 均由 git merge-base --is-ancestor <tip> main 核验为已包含;不是本轮重新执行合并」。这句话很重要——它把「历史已包含」和「本轮又合了一次」区分开,避免把盘点写成新的变更。
分支数量随时间的变化也能从这三份记录读出来:10-01 提到 2.0.0 的 7 个分支都指向同一提交 53a2d31;10-02 是 68 个分支、63 个已并入;10-05 的 分支审查 是对 29 条分支的逐条裁决(含 main独有/分支独有 计数);10-16 已是 89 个分支、84 个祖先。最终在 分支与工作树归档 中收敛为「122 个旧分支的完整 tip 保存在 bundle 中、89 个干净工作树退休」。
四、有意保留的四条分支:判据与源码依据
这是全文最关键的一节,因为「不合并」比「合并」更需要理由。原文表格完整如下:
| 分支 | 未并入的提交 | 原因 |
|---|---|---|
codex/github-source-archive |
8556fc7 2d2a3a6(09-08) |
GitHub 公开仓库的独立历史,和 main 没有共同祖先,不能也不应合并 |
codex/smooth-motion-experiment |
27c17eb(09-14) |
软件内 Smooth Motion 强制互斥实验,已被 09-14 用户决定取代(只给 NVIDIA App 开启说明),AGENTS.md 要求保留作历史存档 |
codex/beta-latency-ab-20260918 |
24bc11a(09-18) |
给旧 1.4.2beta 引擎加的延迟对比测试;main 里的 tests/integration/CaptureLatencyComparisonTests.cpp 是功能更多的新版 |
codex/avermedia-51-switch-20260917 |
8819ca8(09-18) |
圆刚 5.1 任务关闭时存档的未完成诊断探针,提交说明即为存档,不是产品功能 |
4.1 独立历史:为什么「不能也不应合并」
codex/github-source-archive 保存的是公开仓库的独立历史,与开发 main 没有共同祖先。没有共同祖先时,Git 的 merge 会直接报 refusing to merge unrelated histories;即使加 --allow-unrelated-histories 强行合并,也会产生一个把两套完全不同文件树塞进同一祖先的合并提交,后续所有 git log --follow、git blame、git bisect 都会被污染。这条分支的用途是「源码存档」,正确做法是保留其 tip 作为独立引用,而不是并进产品线。
4.2 被用户决定取代的实验:Smooth Motion
codex/smooth-motion-experiment 是被「决定」淘汰的分支,而不是被「代码」淘汰的。现行说明在 SMOOTH_MOTION_HELP_2026-09-14,指向的做法是「只给 NVIDIA App 开启说明」,即把强制互斥的软件内实现撤掉,改为文档指引。因此这条分支的价值是「记录被否决的方案」,必须保留——这正是文档提到 AGENTS.md 要求保留历史存档的含义。
从仓库的协作规则也能看出这一原则:AGENTS.md 的条目反复出现「不合 main、不 push/Release」「保留作历史存档」这类表述,并单独要求「脏树、唯一脚本/配置/素材、SDK/模型原件、Git 共用库和许可对应源码保护;归档分支须有 tip 映射和 verify 过的 bundle」。分支治理在这套规则里不是「删干净」,而是「可恢复的收拢」。
4.3 被新版取代的对照测试:beta-latency-ab
文档给的理由很具体:main 里的 tests/integration/CaptureLatencyComparisonTests.cpp 是功能更多的新版。这个判断可以直接读源码验证。该测试是一个独立可执行程序,wmain 的参数解析如下(tests/integration/CaptureLatencyComparisonTests.cpp):
argc只能是 2、6、7、8、9(argc != 3 && argc != 7 && argc != 8 && argc != 9时返回 2),即支持「目录 + 秒数」的最简形态与带完整参数的形态;- 第 3 个参数是后端
backend,默认dlss,只接受dlss或xess; - 第 4 个参数是倍率
multiplier,默认 4,只接受 2 或 4; - 第 5、6 个参数是
native与resize两个布尔开关; - 第 7 个参数是档位
profile,默认4k30,只接受4k30或1440p60,据此推出目标分辨率与帧率(3840×2160@30 或 2560×1440@60); - 第 8 个参数是
bufferMode,默认 0,大于 2 直接拒绝; - 秒数限制在 3–120 秒之间,越界返回 2。
它还要求设备名精确匹配 VC-007PRO,并按 NV12 与目标分辨率/帧率筛选采集格式;找不到就打印可用格式列表并返回 3。这说明它是一份面向具体采集卡、可复现参数组合的对照工具,而不是通用探针。旧 1.4.2beta 分支里的版本只服务于「旧引擎不变」的对照需求,功能面更窄,因此保留旧分支作为证据、在新版继续演进,是合理取舍。
4.4 未完成的诊断探针:avermedia-51-switch
这一条被保留的理由是「提交说明即为存档」。仓库里保存了当时的调研与实施记录:AVERMEDIA_5P1_CAPTURE_FEASIBILITY_2026-09-17 与 AVERMEDIA_5P1_SWITCH_IMPLEMENTATION_2026-09-17。可行性报告的结论部分写得很克制:当前软件状态下,从 GC553G2 拿到的只有 2.0 PCM;并列出后续要补的两个前置诊断(设备名日志、载荷嗅探)与未验证项「真机 5.1 至今一次都没成功过」。
这类分支的处置要点是:不能因为「最终没做成」就删掉,因为它记录了失败路径(例如把 VFW_E_NOT_FOUND 当成 PCM 停滞而反复重连 7 次、刷 21 行日志),这些结论能防止后人重复踩坑。
值得注意的是,圆刚音频后来确实以另一条路径落进了产品线:src/source/AverMediaAudioSwitch.cpp、src/source/AverMediaVendorAudio.cpp、src/source/AverMediaAudioCarrier.cpp,对应报告是 PR63_AVERMEDIA_AUDIO_REPORT_2026-10-18 与 PR64_AVERMEDIA_REPORT_2026-10-19。也就是说,09-17 的存档分支与 10-18/10-19 的落地实现是两件事:前者是未完成探针,后者才是产品功能。把两者混为一谈,正是分支治理最容易犯的错误。
五、工作区未提交改动:定性而非清理
原文第二张表处理的是「不在任何分支里」的东西:
| 位置 | 内容 | 处理 |
|---|---|---|
桌面原目录 C:/Users/123/Desktop/Veyra DLSS Video Player(codex/ui-qml-migration-20260925) |
62 个文件,全部停在 09-27 13:07 之前:P0/P1 调色工作搬到 E 盘之前的起点 | 与 10-01 存档 archives/merge-2.0.0-20261001/desktop-tracked-changes.patch 逐字节相同;之后的版本已在 main。按规定不改动桌面原目录 |
worktrees/xess143-compare-20260921-r1(游离) |
6 个文件:把 XeSS 节奏控制退回 1.4.3 行为的 A/B 对比实验 | 排查用的对照版本,不是产品改动 |
worktrees/dlss-recovery-baseline-20260920(游离) |
1 个测试文件:1.4.3 基线上的测试调整 | 同上 |
三个判定方法值得单独记住:
- 逐字节相同是比「看起来一样」更强的结论。原文说桌面目录的改动与 10-01 存档的 patch 逐字节相同,可复核方式是对两份补丁取哈希:
只有哈希一致,才能断言「这里的改动没有新内容,之后的演进都在 main」。sha256sum archives/merge-2.0.0-20261001/desktop-tracked-changes.patch <另一份副本> - 文件数从 50 变成 62:10-01 的记录写的是「50 个已修改文件」,10-02 写的是「62 个文件」。两者不矛盾——口径不同(已跟踪修改 vs 全部含未跟踪),但引用时必须带上原文口径,不能把 62 说成「新增了 12 个文件」。
- 游离(detached)工作树里的东西默认不算产品改动。
xess143-compare与dlss-recovery-baseline都是对照基线,判断依据是「它是否被任何长期分支引用」以及「它是否被验收记录引用」,而不是「它是否存在」。
Git 里可以用一条命令看清这类工作树的全貌:
git worktree list --porcelain
# 对每个游离 HEAD,确认所指提交是否已在 main:
git merge-base --is-ancestor <worktree-HEAD> main && echo "已包含" || echo "仅用于对照"
六、可选清理:为什么「删分支名」不等于「丢提交」
原文最后一节明确写了:可选清理未执行,需用户另行同意。清单只有两条:
- 删除 63 个已并入 main 的旧分支名(提交本身都在 main 里,随时可以从提交号恢复);
- 删除已完成任务的 worktree 目录(
worktrees/下 17 个,及桌面out/下的旧工作区)。
这两条的安全性来源不同:
- 删分支名 = 删
refs/heads/<name>。只要 tip 是 main 的祖先,提交对象仍被 main 引用,git gc不会回收。恢复只需git branch <name> <sha>; - 删 worktree 目录 = 删工作目录。前提是该工作树没有未提交改动;若有,必须先导出 patch 或保留原位。原来的 10-01 记录里就专门标注了两类「不要清理」的工作树:
beta-latency-ab-20260918和桌面out/worktrees/avermedia-51,因为它们检出的正是含独有提交的分支。
后续的 分支与工作树归档 把「清理」升级成了「归档 + 可恢复」,并给出恢复命令:
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 这一步不能省:它校验 bundle 的完整性与前置依赖,只有 verify 通过,第二行的 fetch 才有意义。归档文档还强调「工作树另用 git worktree add 创建」「不要直接把备份压到现有源树」,以及 6 个脏树的 index/worktree patch 与未跟踪文件在 zip 中逐项 SHA 校验——这些约束的目的都是同一个:任何「清理」都必须可逆。
七、后续分支工作流:从「多阶段别名」到「单线 + 短命分支」
10-01 记录的第 6 节定下了规则,10-02 的盘点是把规则执行完的最后一步。规则可以概括为三条:
- main 是唯一主线。新需求从 main 开短命分支(命名形如
codex/fix-xxx-日期),验收后合回 main 并删掉分支名; - 不再保留「同一提交的多个阶段别名」。阶段点用
checkpoint/*标签标记(既有checkpoint/ui-mig-*保持不动)。这条直接对应 10-01 的发现:2.0.0 的 7 个分支全部指向同一提交53a2d31,它们是「不同阶段留下的指针」,不是 7 条并行开发线; - push、Release、Runtime Pack 上传需要单独授权。这与 AGENTS.md 中反复出现的「不合并 main、不 push/Release」一致。
这套规则在后续记录中被反复实践:10-05 的审查表逐条给出「已在 main 历史内,保留分支」或「历史存档/诊断/撤回实验,非当前产品修复,不合入」;10-16 的核对则把「本轮没有新增产品代码合并」写成明确结论,并附上「没有产品代码、QML、着色器、构建配置或运行库变化,因此本轮未重新构建、未执行 GPU/采集/播放回归」的边界声明。
这条经验对任何多 Agent、多工具协作的仓库都成立:盘点结论必须自带「本轮改了什么、没改什么」两句话,否则读者无法判断某条分支是被合并了,还是只是被记录为「历史上已经合并」。
八、在当前仓库复核这份盘点的操作清单
以下命令按「先看结构、再验祖先、后验改动」的顺序排列,可在完整历史克隆中直接执行。
8.1 结构与索引
- 文档索引:docs/history/INDEX.md,其中 196–199 行集中列出
BRANCH_INTEGRATION_2026-10-16、BRANCH_MAP_2026-10-01/02/05; - 旧路径映射:docs/history/PATH_MAP.json,把
docs/BRANCH_MAP_2026-10-02.md映射到docs/history/reports/BRANCH_MAP_2026-10-02.md。引用这份文档时必须用新路径,否则会 404; - 归档恢复入口:docs/BRANCH_ARCHIVE.md;
- 日常开发入口:docs/DEVELOPMENT.md 第 41 行明确「合并后关闭已完成的工作树/分支;只保留 main、正在做的任务和明确暂停项」。
8.2 一次性枚举与分类
# 所有本地分支及其 tip
git for-each-ref --format='%(refname:short) %(objectname:short) %(committerdate:short)' refs/heads
# 每个分支相对 main 的独有提交数(0 = 已并入)
for b in $(git for-each-ref --format='%(refname:short)' refs/heads); do
printf '%s\t%s\n' "$b" "$(git rev-list --count main..$b)"
done | sort -k2 -n
# 有独有提交的分支,看补丁是否已等价存在于 main
git cherry -v main <branch>
若某个分支独有提交数不为 0,但 git cherry 显示为 - 前缀,说明内容已以不同哈希进入 main——这正是 10-05 记录里「两条 NR 提交纳入」「已由 PERF 最终账本覆盖」这类判断的依据。
8.3 校验「不合并」的四条理由
| 理由类型 | 可执行判定 |
|---|---|
| 无共同祖先 | git merge-base main <branch> 无输出即为无共同祖先;此时禁止 --allow-unrelated-histories 合并 |
| 用户决定取代 | 查 docs/history/reports/ 下对应日期的说明文档,确认「现行方案」是否已切换 |
| 已被新版取代 | 对比两版测试文件的功能面(如本文 4.3 的参数矩阵),判断记录价值是否只在于历史 |
| 未完成诊断存档 | 查提交说明与同期报告,确认结论是「未验证/已关闭」而非「已实现」 |
8.4 校验未提交改动的「无新内容」结论
# 1) 工作树全貌(含游离 HEAD)
git worktree list --porcelain
# 2) 补丁哈希对比(跨目录比较同一份存档)
sha256sum <路径A>/desktop-tracked-changes.patch <路径B>/desktop-tracked-changes.patch
# 3) 若需要长期保留,导出为可重放的补丁
git diff --binary > <name>.patch
git status --porcelain=v1 -uall > <name>-status.txt
注意 git diff 默认不含未跟踪文件,必须配合 -uall 的状态清单或单独打包未跟踪目录,否则「存档」会漏内容。这正是归档文档里要把「index/worktree patch 与未跟踪文件」分开保存并逐项 SHA 校验的原因。
九、常见误判与规避
- 把「分支名存在」当成「内容未合并」。判定标准是
merge-base --is-ancestor,不是分支列表。 - 把「合并提交」当成「新功能」。10-02 的五条记录里,有的合并只是把已验收分支接入主线;判断是否引入产品变化,要回到该分支的验收报告,例如导出页那一轮有独立的 执行与验收记录。
- 把「未完成存档」当成「可用功能」。
avermedia-51-switch是典型:报告里写明「真机 5.1 至今一次都没成功过」,任何引用都不能写成「已支持 5.1」。 - 把「清理」当成「无风险」。删分支名安全的前提是 tip 已在 main;删工作树安全的前提是没有未提交内容。两个前提缺一不可。
- 忽略浅克隆的证据边界。当前仓库只有单个提交,
git cat-file查不到文档中的短哈希;此时应明确说明「提交号来自历史记录,需完整历史或 bundle 复核」,而不是宣称已验证。
十、结语:一份盘点文档的工程价值
BRANCH_MAP_2026-10-02 篇幅不长,但它同时完成了四件事:给出 main 的准确基线、把五次合并与具体功能模块对应起来、为四条保留分支写明可复核的判据、把工作区里的「非分支内容」定性清楚。这些信息在今天依然有用——你可以在 src/engine/ExportQueue.cpp 中读到导出队列的状态机,在 src/ui/bridge/Status.cpp 中读到按 LUID 过滤的单卡 GPU 采样,在 i18n/catalog.json 中读到 2739 条四语词表,在 tests/integration/CaptureLatencyComparisonTests.cpp 中读到那份「功能更多的新版」对照测试的参数矩阵。分支治理的终点不是干净的 git branch 输出,而是「每一条保留与删除都能指向一段可验证的历史」——这份文档正是按这个标准写成的。