MooTool Next Compose:Vault Git 分叉后 `fetch` 同时刷新 ahead/behind 的 Electron 对齐实现
MooTool Next Compose:Vault Git 分叉后 fetch 同时刷新 ahead/behind 的 Electron 对齐实现
导读
本文讲解 MooTool 桌面套件的 Next Compose(Kotlin/Compose Multiplatform)版本中,Vault Git 面板如何通过与 Electron 版本一致的行为处理「本地与远端各自有新提交」的分叉(diverged)分支:一次 git fetch --prune origin 之后,git status --branch 能同时报告 ahead >= 1 与 behind >= 1,且不自动 merge 工作区。全文以 DIFF-479 记录(479-git-fetch-diverged-ahead-behind-parity.md)为骨架,并结合 GitEngine 源码与集成测试,说明该行为从命令、解析到测试验证的完整链路。
背景:ahead/behind 的解析来源与覆盖缺口
MooTool Next 系列产品中,Vault(本地知识库)的 Git 状态由 status 接口承载。无论是 Electron 版还是 Compose 版,ahead/behind 都来自同一个源头:
git status --porcelain=v1 -z --branch --untracked-files=all
-
Electron 版:
VaultGitService.status用正则从--branch输出的 branch 行解析计数,见 next/electron/main/vaultGitService.ts:const ahead = Number(/ahead (\d+)/.exec(branchLine)?.[1] ?? 0) const behind = Number(/behind (\d+)/.exec(branchLine)?.[1] ?? 0) -
Compose 版:
GitEngine.status以相同方式解析,见 GitEngine.kt:ahead = Regex("ahead (\\d+)").find(parsed.branchLine)?.groupValues?.get(1)?.toIntOrNull() ?: 0, behind = Regex("behind (\\d+)").find(parsed.branchLine)?.groupValues?.get(1)?.toIntOrNull() ?: 0,
Git 面板中「拉取远程」之前的 fetch 动作,两端也一致地采用同一命令:
git fetch --prune origin
- Electron:
case 'fetch': return this.result(<a href="https://link.gitcode.com/i/8f68eb0d1e3a1b3bee6e72bc3200d467" target="_blank">'fetch', '--prune', 'origin'], true)([vaultGitService.ts) - Compose:
run(listOf("fetch", "--prune", "origin"), root, isolateConfig, token, REMOTE_TIMEOUT_MS)(GitEngine.kt)
此前 DIFF-474 与 DIFF-478 已分别覆盖了「本地单向落后」与「远端分支被删除后的 --prune 清理 tracking ref」两种场景(见 474-git-fetch-prune-behind-parity.md 与 478-git-fetch-prune-stale-ref-parity.md)。但它们都没有覆盖分叉场景:本地与远端各自提交了新的 commit,此时 fetch 之后分支应同时呈现 ahead 与 behind,且工作区不应被自动合并。这正是 DIFF-479 要锁定的行为。
变更:用集成单测锁定分叉后的 fetch 语义
DIFF-479 的核心变更是一个命名清晰、可复现的集成测试:
- 测试方法:
GitEngineTest.fetchReportsAheadAndBehindWhenBranchesDiverge(位于 GitEngineTest.kt),在真实的 Git 命令之上复现「分叉 → fetch → 同时出现 ahead/behind → 工作区不被 merge」的完整链路; - 登记 fixture:在 docs/fixtures/electron-next-vaultGitService-vitest.md 登记
fetch-diverged-ahead-behind用例,与已有fetch-prune-behind、fetch-prune-stale-ref形成系列。
测试的仓库拓扑
测试通过 Files.createTempDirectory 一次性搭建三个临时仓库,模拟真实的协作拓扑:
| 角色 | 用途 |
|---|---|
bare(裸仓库) |
充当 origin,以 git init --bare -b main 创建 |
upstream(上游工作副本) |
先提交基础 commit,再在分叉后提交远端独有的 commit 并 push |
client(本地工作副本) |
克隆后提交本地独有的 commit,模拟「本地领先」 |
测试的关键步骤序列如下:
- 初始化分叉基础:
upstream克隆bare后提交shared.txt(v1)并 push;client克隆同一 URL。 - 本地提交:
client新增local-only.txt并提交Local only,此时本地领先远端 1 个 commit。 - 远端提交:
upstream新增remote-only.txt并提交Remote only后 push,使远端也领先本地 1 个 commit——两个分支正式分叉。 - fetch 前断言:
remote-only.txt尚不存在于client工作区(assertFalse(Files.exists(...)));GitEngine.status(client).behind == 0,ahead >= 1——分叉发生但尚未fetch,behind自然为 0。
- 执行 fetch:
GitEngine.fetch(client, isolateConfig = true)返回success。 - fetch 后断言(测试核心):
ahead >= 1与behind >= 1同时成立——fetch 只是刷新远端 tracking ref,两个方向的计数都能正确呈现;remote-only.txt仍不存在——fetch 不 merge 工作区,不会把远端内容擅自落盘。
每个断言背后的含义
behind == 0(fetch 前)对比behind >= 1(fetch 后)验证了「behind 计数依赖于 tracking ref 的新鲜度」这一关键事实:git status --branch的[ahead x, behind y]是相对origin/<branch>而言的,而该 ref 只有在fetch之后才被更新。ahead >= 1在 fetch 前后都成立,说明 fetch 不会回退本地的领先状态——本地独有 commit 始终被如实上报。- 远端文件不落盘,验证了「fetch 只是下载对象与更新 ref,绝不触碰工作区」这一 Git 基本语义被产品层正确沿用,与 DIFF-474 中「fetch 更新 behind 但不拉取工作区」的约束保持一致。
源码原理:GitEngine.status 与 fetch 的实现细节
测试只是入口,行为最终由 GitEngine.kt 中的两个核心函数承载。
status:porcelain 解析是 ahead/behind 的唯一数据源
status 在确认仓库可用、且 Vault 根目录与 git rev-parse --show-toplevel 一致后,执行:
run(listOf("status", "--porcelain=v1", "-z", "--branch", "--untracked-files=all"), root, isolateConfig)
随后 parsePorcelain 以 \u0000 切分记录(-z 输出格式,规避空格与文件名转义问题),取出第一条记录作为 branch 行;ahead/behind 分别用 Regex("ahead (\\d+)") 与 Regex("behind (\\d+)") 提取。branch 行典型的形态是:
## main...origin/main [ahead 2, behind 1]
值得注意的还有 isolateConfig = true 参数:GitEngine 执行命令时会设置 GIT_CONFIG_GLOBAL 与 GIT_CONFIG_SYSTEM 为 /dev/null(Windows 为 NUL),避免用户本机的全局 Git 配置(如别名、credential helper 干扰)影响 Vault 操作的可复现性——这也是所有集成测试默认开启隔离的原因。
fetch:带前提校验的 --prune 命令
fetch 通过 requireRemote 包裹,先做两重前置校验:
- 仓库未初始化 → 返回
Git repository is not initialized; - 未配置
origin→ 返回No origin remote is configured。
通过后才真正执行:
run(listOf("fetch", "--prune", "origin"), root, isolateConfig, token, REMOTE_TIMEOUT_MS)
--prune 保证 fetch 同时清理远端已删除分支对应的 origin/* tracking ref(DIFF-478 的覆盖点)。命令使用 REMOTE_TIMEOUT_MS = 120_000L(网络命令放宽到 120 秒,普通本地命令为 TIMEOUT_MS = 30_000L),并支持 token 注入——当传入了 token 时,executeRun 会生成临时 askpass 脚本并设置 GIT_ASKPASS/SSH_ASKPASS,同时以 GIT_TERMINAL_PROMPT=0 关闭交互式提示,保证在无人值守环境下安全失败而非挂起。
分叉场景下的行为链路小结
client 提交本地 commit → ahead = 1, behind = 0
upstream push 远端 commit → (client 未 fetch, 仍 ahead = 1, behind = 0)
GitEngine.fetch (--prune) → 更新 origin/main tracking ref
GitEngine.status → ahead >= 1 且 behind >= 1(同时成立)
工作区 → 未被 merge(remote-only.txt 不存在)
Electron 对照:VaultGitService 的同源实现
Compose 的 GitEngine 并非独立设计,而是与 Electron 版 VaultGitService 逐条对齐。两者的对应关系可从 next/electron/main/vaultGitService.ts 中直接印证:
- fetch 动作:
fetch→git fetch --prune origin(L196-L197); - status 解析:同样基于
git status --porcelain=v1 -z --branch --untracked-files=all,并用同一正则提取ahead/behind(L68-L72); - behind 更新语义:fetch 只刷新 tracking ref,不触碰工作区,两端一致。
在 docs/fixtures/electron-next-vaultGitService-vitest.md 的对照登记表中,本 DIFF 归属 fetch-diverged-ahead-behind 用例,紧跟在 DIFF-474 的 fetch-prune-behind 与 DIFF-478 的 fetch-prune-stale-ref 之后,三者共同覆盖了 fetch 的全部三态:单向落后、远端删分支、双向分叉。
验证方式
该测试属于 desktopTest,在 macOS/Linux 开发机上按 DIFF 记录中的方式运行(需 JDK 21):
export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
./gradlew :composeApp:desktopTest --offline
两点说明:
--offline让 Gradle 完全使用本地依赖缓存,保证结果可复现;若需要网络依赖,可去掉该参数;- 测试通过
assumeGit()前置跳过——当执行环境中不存在git可执行文件时,相关用例会被 JUnit 跳过而非失败(例如 CI 容器未安装 Git 时),这是刻意设计的健壮性兜底。
整个 desktopTest 是 MooTool Next Compose 与 Electron 行为对齐的持续验证载体,运行产出的覆盖率与通过数会同步记录在 docs/acceptance.md 中,本用例即为其构成之一。
总结
DIFF-479 用一条端到端集成测试补齐了 Compose GitEngine 在「本地与远端各自有新提交」这一真实协作场景下的行为对齐:fetch --prune origin 之后 status 必须同时呈现 ahead 与 behind,且工作区保持原样、不被自动 merge。从 Electron 的 VaultGitService 到 Compose 的 GitEngine,ahead/behind 始终由 git status --porcelain=v1 -z --branch 的 branch 行驱动,--prune 与网络超时、配置隔离、askpass token 注入等细节共同保证了该能力在多平台桌面环境下的可用性。结合 DIFF-474、DIFF-478 与 DIFF-479,fetch 的完整行为矩阵已由集成测试固化,为后续的拉取、合并、冲突处理流程提供了可靠前提。