MooTool Next Compose 的 Git 仓库 pull 冲突期禁用机制:DIFF-624 切片实现与双层防线解析
MooTool Next Compose 的 Git 仓库 pull 冲突期禁用机制:DIFF-624 切片实现与双层防线解析
导读
本篇技术指南围绕 MooTool 桌面工具链 Compose 版本(next-compose)中 Vault Git 远程面板(A03) 的一个行为切片展开:当工作区存在未解决的合并冲突(conflicts > 0)时,界面上的 pull 按钮必须禁用。文章将完整剖析 DIFF-624 的实现范围、纯函数式的按钮启用判定逻辑、GitEngine.pull 引擎侧守卫,以及配套的单元测试、真实 Git 场景产品证据流与桌面截图证据帧(217)。读完你将掌握:冲突计数 conflicts 如何从 git status 解析而来、UI 与引擎两层防线的职责边界,以及为何 fetch 在冲突期保持可用而 pull 必须禁用。
DIFF-624 切片定位:完整冲突期操作矩阵的最后一环
DIFF-624 的基线是 DIFF-623(工作区),文档将这一改动明确归类为“A03 Vault Git 未解决冲突期 pull UI 禁用”,核心范围只有一句话:GitVaultRemotePresentation.pullEnabled / pullActionEnabled 在 conflicts > 0 时禁用 pull。但这句话背后是一套完整的“未解决冲突期操作矩阵”:
| 操作 | merging=true(merge/rebase 进行中) |
conflicts>0 且 merging=false |
相关切片 |
|---|---|---|---|
| fetch | ✅ 可用(仅要求 remote) | ✅ 仍可用 | DIFF-619 |
| pull | ❌ 禁用 | ❌ 禁用(本切片补齐) | DIFF-624 |
| push | ❌ 禁用 | ❌ 禁用 | DIFF-623 |
| commit | ❌ 禁用 | ❌ 禁用(commitEnabled) |
DIFF-618 |
原文档特别强调“不重复 619/623”:DIFF-619 锁定的是“rebase 进行中 fetch 可用 + pull 因 merging=true 禁用”场景;DIFF-623 锁定的是“push + conflicts”;而本切片补齐的是 pull + conflicts 且 merging=false 的场景——即冲突计数存在、但当前并不处于一个活动的 merge/rebase 状态(例如曾经 abort 后遗留的未解决冲突、或非交互式合并遗留的 unmerged 路径)。这一切片落实了 DIFF-520 中“Pull 按钮要求 remote、非 merge/rebase 进行中且 conflicts == 0”的设计,并与 push/commit 的冲突期禁用策略保持一致。
冲突计数的来源:GitStatus.conflicts 如何从 git CLI 解析
理解 pull 禁用逻辑,首先要弄清 conflicts 数据从哪来。桌面端核心引擎 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"
)
其中 conflicts 并不是直接读取 git 的某个输出字段,而是由 status 函数对 git status --porcelain 解析出的变更列表计数得到(GitEngine.kt):
GitStatus(
...
changes = parsed.changes,
conflicts = parsed.changes.count { it.conflict },
merging = operation != "none",
operation = operation
)
而单个变更的 conflict 布尔值,判定规则是 porcelain 双字符状态码:code.contains('U')(如 UU/DU/UD 等 unmerged 组合)或 AA、DD(双方同时新增/删除的目录冲突)(GitEngine.kt)。
val conflict = code.contains('U') || code == "AA" || code == "DD"
changes += GitChange(path, original?.ifBlank { null }, code, conflict)
这一设计意味着:只要 git status 中存在任一 unmerged 路径,conflicts 就大于 0,无论当前是否处于 merging 状态——这正是 DIFF-624 要覆盖的“有冲突计数但非 merging”场景的底层依据。
核心实现:pullEnabled 与 pullActionEnabled 的判定逻辑
本切片的主战场是纯函数对象 GitVaultRemotePresentation.kt,它负责 Vault Git 面板中所有与远程操作相关的按钮启停,并且源码注释明确它“对齐 Electron 只读 status.remote”:
fun pullEnabled(persistedRemote: String, merging: Boolean, conflicts: Int = 0): Boolean =
GitOperationPresentation.pullEnabled(networkRemotePresent(persistedRemote), merging) &&
conflicts == 0
fun pushEnabled(persistedRemote: String, merging: Boolean, conflicts: Int = 0): Boolean =
GitOperationPresentation.pushEnabled(networkRemotePresent(persistedRemote), merging) &&
conflicts == 0
fun pullActionEnabled(
persistedRemote: String,
merging: Boolean,
busy: Boolean,
conflicts: Int = 0,
): Boolean = !busy && pullEnabled(persistedRemote, merging, conflicts)
pullEnabled 是两层与运算的合成结果:
- 基础层来自 GitOperationPresentation.kt 的通用判定——要求 remote 已持久化且非 merge/rebase 进行中:
fun pullEnabled(remotePresent: Boolean, merging: Boolean): Boolean = remotePresent && !merging - 冲突层是 DIFF-624 新增的约束——
conflicts == 0。
而 pullActionEnabled 进一步叠加 !busy(面板忙态禁用),这是 VaultGitDialog 所有工具栏按钮的统一约定。需要注意:pullEnabled 与 pushEnabled 在“未配置 remote”“merge 进行中”时的判定完全一致,只是冲突层在 DIFF-624 之前 push 已先行实现(DIFF-623),本切片为 pull 补齐了同一约束,使两者语义完全对称。
UI 调用点:VaultGitDialog 顶栏按钮如何消费该判定
纯函数判定最终在 VaultGitDialog.kt 的顶栏工具栏中被消费。Pull 按钮每次根据实时 GitStatus 计算可用性:
MooButton(
container.t("git.pull"),
p5Toolbar = true,
enabled = GitVaultRemotePresentation.pullActionEnabled(
status.remote,
status.merging,
busy,
conflicts = status.conflicts,
),
onClick = { runAction(workingTree = GitVaultFlushAction.Pull) { GitEngine.pull(root, token = token()) } },
)
同一区块中 fetch / push 按钮的调用形成了完整的对照:
- fetch:
fetchActionEnabled(status.remote, busy)——只要求 remote 与!busy,不检查merging和conflicts,即“冲突期仍可用”; - pull:
pullActionEnabled(status.remote, status.merging, busy, conflicts = status.conflicts)——本切片新增的冲突约束在此生效; - push:
pushActionEnabled(status.remote, status.merging, busy, conflicts = status.conflicts)——DIFF-623 已实现的对称约束。
面板在 runAction 成功后还会重新执行 GitEngine.status(root) 刷新 GitStatus,因此一旦冲突解决完毕,conflicts 归零,pull 按钮会自动恢复可用,无需手动刷新。
引擎侧防线:GitEngine.pull 的守卫优先级
UI 禁用只是第一道防线;即使绕过 UI 直接调用引擎,GitEngine.pull 也内置了同样的守卫,且冲突检查先于 remote 检查:
fun pull(root: Path, isolateConfig: Boolean = false, token: String = ""): GitActionResult = locked(root) {
val current = status(root, isolateConfig)
if (!current.repository) return@locked GitActionResult(false, "Git repository is not initialized")
if (current.merging) return@locked GitActionResult(false, "Finish or abort the current merge/rebase before pulling")
if (current.conflicts > 0) {
return@locked GitActionResult(false, "Resolve all conflicts before pulling")
}
if (current.remote.isBlank()) return@locked GitActionResult(false, "No origin remote is configured")
val result = run(listOf("pull", "--no-rebase", "origin"), root, isolateConfig, token, REMOTE_TIMEOUT_MS)
...
}
守卫顺序值得注意:先检查 merging,再检查 conflicts > 0,最后才检查 remote 是否存在。这对应了 GitPullGuardTest 中“merge 中拒绝优先于 missing-remote 提示”(mergeInProgressRejectedBeforeMissingRemoteMessage)以及“冲突未解决时 pull 被拒绝且提示包含 merge 字样”(pullBlockedWhileMergeConflictsRemain)两条用例的断言。命令实际执行的是 git pull --no-rebase origin,超时上限为 REMOTE_TIMEOUT_MS(120 秒,区别于本地命令的 30 秒)。GitEngine.push 采用了完全相同的三层守卫结构(repository → merging → conflicts),保证 UI 与引擎行为一致。
单元测试:pullDisabledWhileUnresolvedConflicts
本切片对应的核心单测位于 GitVaultRemotePresentationTest.kt 的 pullDisabledWhileUnresolvedConflicts,它是 DIFF-624 文档中明确点名的用例:
@Test
fun pullDisabledWhileUnresolvedConflicts() {
val remote = "https://x.git"
assertFalse(
GitVaultRemotePresentation.pullActionEnabled(
persistedRemote = remote,
merging = false,
busy = false,
conflicts = 1,
),
)
assertTrue(
GitVaultRemotePresentation.pullActionEnabled(
persistedRemote = remote,
merging = false,
busy = false,
conflicts = 0,
),
)
}
测试特意使用 merging = false 与 conflicts = 1 的组合,精确锁定“有冲突计数但非 merge 进行中”这一 DIFF-624 独有场景(与 DIFF-619 的 merging=true 场景形成互补)。同一测试类还通过 fetchStaysEnabledDuringMergeWithConflicts 验证了冲突期间 fetch 保持可用、pull 被禁用的对照语义:
assertTrue(GitVaultRemotePresentation.fetchActionEnabled(remote, busy = false),
"fetch stays enabled during merge/rebase conflicts (Electron VaultGitDialog)")
assertFalse(GitVaultRemotePresentation.pullActionEnabled(
persistedRemote = remote, merging = true, busy = false, conflicts = 2))
产品证据流:真实 merge/rebase 场景中的 pull 断言
除了纯函数单测,DIFF-624 文档还要求“merge/rebase 产品证据流传入 conflicts”。这意味着在真实 Git 仓库中构造冲突,通过 GitEngine 走完整流程并断言 pull 的启停。以 GitMergeProductEvidenceFlowTest.kt 为例,测试用 GitEngine 在本地裸仓库 + upstream + clone 的三仓库拓扑中制造冲突(上游修改 evidence-conflict.json,本地修改同一文件后 GitEngine.pull 必然失败):
- 冲突阶段(§B):
status.conflicts >= 1,同时断言pushActionEnabled、pullActionEnabled、commitActionEnabled全部为false,而fetchActionEnabled为true,并执行真实的GitEngine.fetch确认成功; - 解决阶段:
GitEngine.resolveConflict(..., "theirs")后status.conflicts == 0,mergeContinueActionEnabled恢复为true; - 完成阶段:
continueOperation结束后operation == "none",pullActionEnabled/pushActionEnabled重新恢复为true(“pull re-enabled after merge completes”)。
GitRebaseProductEvidenceFlowTest.kt 对 rebase 场景重复了同样的断言流程,并显式注释“pull must stay disabled during rebase §C while conflicts remain”,证明该约束对 merge 与 rebase 两条冲突路径都成立。
证据帧 217:桌面截图捕获测试
DIFF-624 的验证不仅停留在断言层面,还要求产出可直观核对的 UI 证据帧。证据帧编号 217 由 GitVaultPullDisabledConflictsCaptureTest.kt 生成:
- 使用 Compose 桌面 UI 测试框架
runDesktopComposeUiTest(width = 480, height = 120),在浅色 modern 主题下渲染一个真实的MooButton; - 按钮文案来自中文 i18n(
Translator(AppLanguage.ZhCN)的git.pull),enabled直接传入:GitVaultRemotePresentation.pullActionEnabled( persistedRemote = "https://example.git/repo.git", merging = false, busy = false, conflicts = 2, ) - 截图输出到
docs/evidence/2026-09-15-inspector-screencapture/windows/217-compose-git-pull-disabled-unresolved-conflicts-tab-focus.png,并断言文件非空(file.length() > 500)。
与 DIFF-623 的帧 216(GitVaultPushDisabledConflictsCaptureTest,同样 merging=false + conflicts=2)形成姊妹帧,两帧共同证明“未解决冲突、非 merge 进行中”时 pull 与 push 按钮均处于禁用态。整个“截图证据”体系由 product-evidence-common.sh 等脚本支撑,作为跨平台行为一致性的可读凭据。
验证命令与运行前提
按文档约定,本切片的全部验证依赖 JDK 21,在 next-compose 目录下执行:
./gradlew :composeApp:desktopTest --offline --no-daemon
其中 --offline 保证使用本地 Gradle 依赖缓存,--no-daemon 避免常驻守护进程干扰。涉及真实 git CLI 的测试(如 GitPullGuardTest、merge/rebase 产品证据流)会在 GitEngine.detect().available 为 false 时通过 JUnit Assume 自动跳过,因此即使测试机未安装 git,纯函数单测与 UI 捕获测试仍可正常执行。
小结
DIFF-624 看似只改动了几个布尔表达式,实则是 Vault Git 冲突期“UI 提示 → 纯函数判定 → 引擎守卫 → 截图证据”完整闭环的一部分。从 GitOperationPresentation 的基础约束、GitVaultRemotePresentation 的 conflicts == 0 增量,到 GitEngine 的 pull 守卫与 status 冲突解析,再到两处产品证据流与帧 216/217 截图,pull 与 push、commit 在冲突期行为完全对齐,而 fetch 始终作为“只读、无副作用”的操作保持可用——这正是未解决冲突期最安全的远程操作策略。