本文详解如何在基于 git2go 的实时协作编辑器中正确处理合并冲突，重点解决“冲突反复出现”的常见问题，涵盖冲突检测、用户介入、索引清理与合并提交的完整闭环逻辑。
本文详解如何在基于 git2go 的实时协作编辑器中正确处理合并冲突，重点解决“冲突反复出现”的常见问题，涵盖冲突检测、用户介入、索引清理与合并提交的完整闭环逻辑。
在使用 git2go（libgit2 的 Go 绑定）构建实时协同编辑环境时，一个典型痛点是：当多人同时修改同一文件区域触发合并冲突后，即使用户手动编辑并保存了冲突标记（如 <<<<<<< HEAD / >>>>>>> master），再次执行 add/commit/push 仍会重复报出相同冲突——这与命令行 Git 的行为不符。根本原因在于：未在用户解决冲突后显式完成“合并提交”（merge commit），且未清理 Git 的合并状态（MERGE_HEAD、index 状态等），导致下一次 MergeAnalysis 仍认为处于未完成合并流程中。
✅ 正确处理流程的核心原则
-
区分两类冲突场景：
- 自动可解冲突（如仅一方修改）：git2go 可直接合并，无需用户干预；
- 需人工介入的冲突（如双方修改同一行）：必须中断流程，将冲突内容（含 Git 标记）返回前端供用户编辑。
-
用户编辑后，必须执行“三步闭环”：
- ✅ 将用户保存后的内容 git add 到索引（调用 index.AddAll + index.Write）；
- ✅ 创建三路合并提交（CreateCommit(..., localCommit, remoteCommit)），而非普通提交；
- ✅ 调用 repo.StateCleanup() 清除 .git/MERGE_HEAD、.git/MERGE_MODE 等残留状态。
⚠️ 关键误区：仅修改文件内容并执行普通提交（CreateCommit(tree, currentTip)）无法终结合并流程，Git 仍视其为“未完成合并”，后续 MergeAnalysis 必然重入冲突路径。
? 实现要点与代码关键片段
以下为生产级处理逻辑的精简核心（已去除错误日志，聚焦主干）：
// 1. 在执行 merge 前，记录索引是否已有冲突（用于后续判断是否需 merge commit）
indexHadConflicts := index.HasConflicts()
// 2. 执行 fetch + merge analysis + merge 操作
err := repo.Merge([]*git.AnnotatedCommit{annotatedCommit}, nil, nil)
if err != nil {
return err // 如网络失败等
}
// 3. 检查 merge 后索引状态
index, _ := repo.Index()
if index.HasConflicts() {
// ❌ 用户需介入：写入含冲突标记的索引，返回错误中断流程
index.Write()
return errors.New("conflicts_detected")
}
// 4. ✅ 无冲突：直接创建 merge commit 并清理状态
treeId, _ := index.WriteTree()
tree, _ := repo.LookupTree(treeId)
localCommit, _ := repo.LookupCommit(currentCommit)
remoteCommit, _ := repo.LookupCommit(remoteBranch.Target())
repo.CreateCommit("HEAD", sig, sig, "Merge commit", tree, localCommit, remoteCommit)
repo.StateCleanup() // ← 至关重要！清除 MERGE_* 状态? 注意事项与最佳实践
- StateCleanup() 不可省略：这是终结 Git 合并流程的唯一可靠方式。缺失它会导致 .git 目录持续保留 MERGE_HEAD，使所有后续 MergeAnalysis 返回 MergeAnalysisNormal，无限循环冲突。
- 避免重复 MergeAnalysis：不要在用户解决冲突后立即再次调用 MergeAnalysis —— 此时应直接 add → commit → push。MergeAnalysis 仅用于拉取远程变更前的预判。
- 索引状态检查时机：应在 repo.Merge(...) 后立即检查 index.HasConflicts()，而非在 add 或 commit 后；否则可能错过冲突或误判。
- 分支一致性：确保 remoteBranch.Target() 指向的是最新 origin/master 提交（通过 remote.Fetch 更新后获取），避免因本地远程引用过期导致错误分析。
✅ 总结
git2go 中的冲突处理不是简单的“检测→提示→重试”，而是一个严格的状态机：
Fetch → MergeAnalysis → (有冲突？→ 用户编辑 → Add → MergeCommit → StateCleanup) : (无冲突 → Fast-forward Commit)。
只有完整走完该闭环，才能让 Git 正确“记住”冲突已被解决，从而实现与命令行 Git 一致的协作体验。将 StateCleanup() 视为合并操作的“收尾仪式”，是避免冲突反复出现的黄金法则。
