MooTool Next Compose:Vault Git 分叉后 `fetch` 同时刷新 ahead/behind 的 Electron 对齐实现

原创2026-10-15 21:26:201,981 阅读
文章标签:开发工具桌面应用MCP 服务

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,模拟「本地领先」

测试的关键步骤序列如下:

  1. 初始化分叉基础:upstream 克隆 bare 后提交 shared.txt(v1)并 push;client 克隆同一 URL。
  2. 本地提交:client 新增 local-only.txt 并提交 Local only,此时本地领先远端 1 个 commit。
  3. 远端提交:upstream 新增 remote-only.txt 并提交 Remote only 后 push,使远端也领先本地 1 个 commit——两个分支正式分叉。
  4. fetch 前断言:
    • remote-only.txt 尚不存在于 client 工作区(assertFalse(Files.exists(...)));
    • GitEngine.status(client).behind == 0,ahead >= 1——分叉发生但尚未 fetch,behind 自然为 0。
  5. 执行 fetch:GitEngine.fetch(client, isolateConfig = true) 返回 success。
  6. 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 的完整行为矩阵已由集成测试固化,为后续的拉取、合并、冲突处理流程提供了可靠前提。

登录后查看全文
MooTool