MooTool Next Compose:Vault Git 顶栏 ahead/behind 同步计数的无远程展示实现(DIFF-325)

原创2026-10-14 19:18:091,883 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool Next Compose:Vault Git 顶栏 ahead/behind 同步计数的无远程展示实现(DIFF-325)

导读

本文围绕 MooTool Next 桌面端(Compose 实现,位于 next-compose)的 Vault Git 顶栏行为差异,解析一条面向跨实现「行为对齐」的设计变更:当本地仓库已完成 git init 但尚未配置任何远程地址(remote)时,顶栏仍应像 Electron 版一样展示 ↑ahead ↓behind 同步计数行。通过阅读本文,你将掌握该变更的触发条件、顶栏渲染逻辑、ahead/behind 数值的来源与解析方式、与远程按钮可用性(fetch/pull/push)的解耦关系,以及对应的自动化验证方法。

一、问题背景:本地仓库无远程时缺少同步计数

1.1 两套实现的行为差异

MooTool 的 Next 系列存在 Electron(next)与 Compose(next-compose)两套桌面端实现,二者在功能上保持对齐。在 Vault Git 面板中,Electron 的 VaultGitDialog(next/src/features/json/VaultGitDialog.tsx)对顶栏同步计数的展示条件是只要求 status.repository 为真:

{status?.repository && <span>{t('json.git.sync', { ahead: String(status.ahead), behind: String(status.behind) })}</span>}

也就是说,Electron 在仓库已初始化、但尚未配置 origin 远程地址时,也会在分支名下方渲染 ↑ahead ↓behind 计数行。

而 Compose 端在本次变更前的实现仅当 status.remote.isNotBlank()(即检测到已配置的远程地址)时才展示该行。这就造成一个可观察的不一致:本地仓库未配置远程时,Electron 有同步计数行,Compose 却没有,属于典型的平台间 UI 对齐缺口,由 next-compose/docs/diff/325-vault-git-sync-without-remote.md 记录为 DIFF-325。

1.2 为什么没有远程也应展示计数

git status --porcelain --branch 返回的分支行(branchLine)本身就可能携带 [ahead N]、[behind N]、[ahead M, behind N] 等同步信息,例如 ## main...origin/main [ahead 2, behind 1]。当本地分支领先于它的 upstream 跟踪引用时,即使尚未配置 origin URL,计数也可能非零。因此「显示同步计数」与「是否配置了远程 URL」本质上是两个独立维度:

  • 是否展示同步行:只取决于仓库是否已初始化(repository);
  • 是否允许 fetch/pull/push:才取决于是否配置了远程(remote)。

DIFF-325 的目标就是把前者从远程配置中解耦出来,与 Electron 保持一致。

二、目标行为:已初始化即展示同步行

根据 DIFF-325 文档的「行为」说明,变更后的规则非常明确:

已初始化仓库时顶栏在分支名下方始终显示 git.sync。

顶栏的完整展示逻辑变为:

仓库状态 顶栏展示内容
未初始化(含 Git 不可用) git.noRepo(分支名区域)
已初始化 分支名 git.branch + 同步计数 git.sync(↑ahead ↓behind)+ 可选的进行中状态、变更/冲突计数、冲突提示等

注意,这里与 DIFF-317(next-compose/docs/diff/317-vault-git-header-no-repo.md)互补:DIFF-317 统一了「未初始化仓库(含 Git 不可用)」时顶栏显示 git.noRepo 的规则,而 git.unavailable 文案仅保留在工作区居中空态;DIFF-325 则统一了「已初始化」时同步计数的展示规则。

三、Compose 端实现剖析

3.1 顶栏渲染:repository 为唯一前置条件

Compose 端顶栏渲染集中在 VaultGitDialog.kt 的 MooOverlay 弹层内。顶栏左侧的 Row 中,通过 when 分支决定内容:

when {
    !status.repository ->
        Text(container.t("git.noRepo"), /* 未初始化:仅显示 noRepo */)
    else -> {
        Text(
            container.t("git.branch", mapOf("branch" to status.branch.ifBlank { "HEAD" })),
            /* 分支名,加粗显示 */
        )
        Text(
            container.t("git.sync", mapOf("ahead" to status.ahead.toString(), "behind" to status.behind.toString())),
            /* 同步计数行,不再检查 status.remote */
        )
        // 进行中操作状态、变更/冲突计数、冲突提示、合并流程提示……
    }
}

关键点在于:git.sync 这行 Text 位于 else 分支内、直接跟随着 git.branch,其渲染完全不依赖 status.remote。也就是说,只要 status.repository == true,无论是否配置了远程地址,同步计数行都会出现。这正是 DIFF-325 的核心改动位置。

3.2 远程行仍然独立存在

需要区分的是:同步计数的展示虽然不依赖远程,但远程编辑行依然存在,且只在 status.available 为真时渲染(见同一文件中的远程行区块),负责远程地址的保存/删除(git.saveRemote / git.removeRemote)。这与 DIFF-327(next-compose/docs/diff/327-vault-git-remote-field-sync.md)定义的 syncRemoteField 规则配合:

fun syncRemoteField(gitStatus: GitStatus) {
    remote = gitStatus.remote.ifBlank { settings.vault.gitRemote }
}

即在 load() 或 runAction 刷新状态后,输入框用 status.remote 优先、回退到设置中的 gitRemote,保证删除 origin 后输入框不至于残留旧 URL。同步计数行和远程输入框自此各司其职:前者只管「仓库是否初始化」,后者管「远程配置的读写」。

四、数据来源:ahead/behind 如何计算

4.1 GitStatus 数据模型

ahead/behind 由 GitEngine.status() 填充,数据模型定义在 GitEngine.kt:

data class GitStatus(
    val available: Boolean,
    val repository: Boolean,
    val version: String = "",
    val branch: String = "",
    val remote: String = "",
    val ahead: Int = 0,
    val behind: Int = 0,
    val changes: List<GitChange> = emptyList(),
    val conflicts: Int = 0,
    val merging: Boolean = false,
    val operation: String = "none"
)

可以看到 ahead、behind 默认值为 0,这保证即使分支行中没有同步信息(例如首次 init 后尚未有 commits、或没有 upstream 跟踪引用),顶栏也能渲染出 ↑0 ↓0 这样的确定数值而不会出现空白。

4.2 解析管线

GitEngine.status() 对仓库执行 git status --porcelain=v1 -z --branch --untracked-files=all,然后:

  1. 用 parsePorcelain 拆分出首条分支行 branchLine 与变更记录;
  2. 用 parseBranch 从 ## main...origin/main [ahead 2, behind 1] 这类字符串中提取分支名;
  3. 用正则 ahead (\d+) / behind (\d+) 从分支行提取两个整数,匹配失败时回退为 0:
ahead = Regex("ahead (\\d+)").find(parsed.branchLine)?.groupValues?.get(1)?.toIntOrNull() ?: 0,
behind = Regex("behind (\\d+)").find(parsed.branchLine)?.groupValues?.get(1)?.toIntOrNull() ?: 0,
  1. remote 单独通过 git remote get-url origin 探测——这一步失败(未配置远程)时 remote 为空字符串,但不影响 ahead/behind 的填充。这正是「无远程也能显示计数」得以成立的数据基础。

4.3 多语言文案

git.sync 的文案定义在 Translator.kt 中,中英文一致使用箭头加数字的紧凑格式:

  • 中文:"git.sync" to "↑{ahead} ↓{behind}"
  • 英文:"git.sync" to "↑{ahead} ↓{behind}"

顶栏将两个占位符分别替换为 status.ahead 与 status.behind,从而直观表达「领先上游 N 个提交、落后上游 M 个提交」的相对状态。

五、与远程操作可用性的解耦

同步计数行不依赖 remote,不代表 fetch/pull/push 也不依赖 remote。远程相关按钮的可用性由 GitVaultRemotePresentation.kt 控制:

fun networkRemotePresent(persistedRemote: String): Boolean = persistedRemote.isNotBlank()

fun fetchEnabled(persistedRemote: String): Boolean =
    GitOperationPresentation.fetchEnabled(networkRemotePresent(persistedRemote))
  • fetch:!busy && remote 非空,冲突/merge 期间仍可用(对齐 Electron);
  • pull:!busy && remote 非空 && !merging && conflicts == 0;
  • push:!busy && remote 非空 && !merging && conflicts == 0(未解决冲突时禁用,引擎侧 GitEngine.push 也会拒绝);
  • 保存远程:受 repository、草稿内容与现有 statusRemote 共同约束。

而 GitEngine.pull / GitEngine.push 在引擎层也会通过 requireRemote 或显式检查拒绝「未配置 origin」的调用。因此 DIFF-325 只是让「信息展示」与「操作能力」彻底分离:展示永远跟随仓库初始化状态,操作依然受远程配置约束。这一分层在代码结构上也非常清晰——展示逻辑在 VaultGitDialog.kt,能力判定在 GitVaultRemotePresentation.kt。

六、测试与验证

6.1 验证命令

DIFF-325 文档给出的验证方式为 Compose 桌面端测试套件:

./gradlew :composeApp:desktopTest --offline

该命令以离线模式运行 desktopTest,不依赖公网,可在本地复现与验证 Git 相关的行为对齐。

6.2 相关单测用例

与 ahead/behind 强相关的测试位于 GitEngineTest.kt:

  • parsesPorcelainStatusAndBranch:验证 parsePorcelain("## main...origin/main [ahead 2, behind 1]...") 能正确保留分支行原始文本,并断言 parseBranch 提取出的分支名为 main;同时覆盖变更记录( M、??、R 、UU)与冲突标记的解析。这是 ahead/behind 解析链路的基础用例。
  • fetchReportsAheadAndBehindWhenBranchesDiverge:构造裸仓库 + upstream + client 三份临时目录,制造「本地只提交」「远程只提交」的分叉场景,断言 fetch 前 behind == 0、ahead >= 1,fetch 后 ahead 与 behind 同时更新,验证「分叉后 fetch 会刷新同步计数且不 merge 工作区」这一与 Electron VaultGitService.status 对齐的行为。
  • automaticCheckpointPushesWhenRemoteConfigured:在配置远程并完成自动 checkpoint 后,断言 GitEngine.status(...).ahead == 0,即 push 成功后领先数归零。

这些用例共同证明:ahead/behind 是一个持续由 git status --branch 输出驱动、并在每次 status/fetch/runAction 后刷新的实时状态字段,不会因为 remote 是否配置而缺省。

七、配套变更与阅读延伸

DIFF-325 并非孤立的改动,它属于 MooTool Next Compose「Vault Git 面板逐项对齐 Electron」系列中的一环,建议结合以下配套文档阅读以获得完整上下文:

总结

DIFF-325 是一次小但精准的「行为对齐」变更:Compose 端 Vault Git 顶栏的同步计数行 ↑ahead ↓behind 从「依赖已配置 remote」改为「只依赖仓库已初始化」,与 Electron 完全一致。其背后由 GitEngine.status() 对 git status --branch 分支行的正则解析驱动,与远程配置完全解耦;而 fetch/pull/push 等网络操作仍由 GitVaultRemotePresentation 严格受远程配置约束。对于多平台桌面应用而言,这种「信息展示维度」与「操作能力维度」的分离设计,是一个值得借鉴的实现范式。

登录后查看全文
MooTool