并行AI编码代理必设的10个Git配置

多个AI编码代理在独立的Git worktree中并行运行时，一个容易被忽略的事实是：默认情况下，所有worktree共享同一份仓库配置文件。第一个代理执行git config user.email，三个任务的身份就全被改写了。本文基于Git官方文档，整理出10个在启动并行编码代理前应当设置的配置项，覆盖身份隔离、冲突可读性、推送拉取行为以及worktree清理。

为什么worktree配置需要单独处理

Git worktree文档只有一句话说明这件事："默认情况下，仓库的config文件在所有worktree之间共享。"这意味着为某个任务设置的配置会渗透到所有任务。更麻烦的是，代理通常不会主动检查这一点，它们只是按惯例执行git config，然后继续工作。

解决办法是开启extensions.worktreeConfig扩展，之后用--worktree参数写入的配置会保存到$GIT_DIR/config.worktree，并覆盖共享文件中的同名设置。这样每个任务可以有独立的提交身份，git log --author=codex就能精确找到某个代理的提交。需要注意两点：如果共享配置里有core.bare或core.worktree，要先把它们移到主worktree的config.worktree；另外旧版Git会拒绝访问启用了该扩展的仓库。

`extensions.worktreeConfig` 是 Git 2.20 引入的仓库级扩展配置项，用于启用 `config.worktree` 文件。启用后，Git 在读取配置时会依次加载共享的 `.git/config` 和每个 worktree 各自的 `.git/worktrees/<id>/config.worktree`，后者中的同名键会覆盖前者。需要注意的是，该扩展一旦启用，旧版本 Git（低于 2.20）会直接拒绝操作该仓库，因此在团队协作或 CI 环境中需确认所有节点的 Git 版本足够新。此外，`core.bare` 和 `core.worktree` 这两个键与 worktree 机制本身存在冲突，Git 文档明确要求将它们从共享配置迁移到主 worktree 的 `config.worktree` 中，否则可能引发路径解析异常。
# 每个仓库执行一次
git config extensions.worktreeConfig true

# 在某个任务的工作树内
git config --worktree user.name "Codex (fix-login)"
git config --worktree user.email codex@example.com

让代理产生的冲突更容易读懂

冲突样式：zdiff3

默认的合并冲突样式只显示"你的版本"和"他们的版本"，丢掉了原始文本。当两个代理重写了同一个函数时，原始版本恰恰是判断谁改了什么的关键。zdiff3在diff3基础上进一步裁掉冲突边缘两侧相同的行，让差异更聚焦。已经处于冲突状态的文件可以用git checkout --conflict=zdiff3重新生成标记。

差异算法：histogram

Git的ort合并策略默认使用histogram对齐变更，但普通diff默认仍是Myers算法。这意味着你审查代码时看到的diff，和实际落地合并时配对行的方式可能不一致。有实证研究（Nugroho、Hata、Matsumoto发表于《Empirical Software Engineering》）指出，在应用补丁的场景下Histogram比Myers更适合呈现代码变更。把diff.algorithm设为histogram可以让审查和合并使用同一套逻辑。

重复冲突：rerere

两个代理分支改动同一批代码行时，同一个冲突可能要在试合并、rebase、下一次rebase中反复解决。rerere.enabled会记录第一次的解决方案并在后续自动重放。记录缓存在rr-cache目录，属于仓库共享目录，因此在一个worktree中解决的冲突可以在其他worktree中复用。默认60天后清理，若记录有误可用git rerere forget <file>撤销。

rerere 全称 "reuse recorded resolution"，是 Git 内置的冲突解决方案缓存机制。它的工作流程是：当合并或 rebase 产生冲突时，Git 将冲突区的规范化哈希作为键，把手工解决后的结果作为值存入 rr-cache 目录；后续遇到相同哈希的冲突时，自动应用已记录的解决方案。rerere.enabled 只开启记录与自动重放，若希望解决后自动暂存文件（省去手动 git add），还需设置 rerere.autoUpdate true。rr-cache 位于共享的 .git 目录下，因此天然跨 worktree 生效，这与本文强调的并行代理场景高度契合。

不打断代理的推送与拉取

每个任务分支都是新建的，没有上游追踪分支。在默认push.default=simple下，代理第一次执行普通git push会失败，还得自己摸索--set-upstream。开启push.autoSetupRemote后，当前分支没有上游时推送会自动建立追踪关系。

代理分支生命周期短。PR合并、服务端删除分支后，本地克隆仍保留origin/hermes/fix-login这类引用。几周下来git branch -r会塞满早已不存在的远程分支。fetch.prune让每次拉取时顺带清理这些失效引用。

处理堆叠任务与查看最新分支

任务B有时从任务A的分支而非main起步。rebase B之后，A仍停留在旧提交上。rebase.updateRefs相当于默认开启--update-refs，会强制更新指向被rebase提交的分支。但文档紧接着说明："在worktree中检出的分支不会以这种方式更新。"如果A的worktree还开着，A不会前进。需要先结束或移除A的worktree，或用git -C ../task-a switch --detach让它脱离检出状态。

git branch默认按名称排序，刚完成的任务会埋在hermes/*列表中间。设置branch.sort -committerdate后按提交时间倒序排列，最新工作排在最前。列表中*表示当前分支，+表示在其他worktree中检出的分支。

rebase.updateRefs 对应 git rebase --update-refs 选项，Git 2.38 起可用。启用后，rebase 过程中会检测哪些本地分支的尖端提交属于被重写的提交范围，并在 rebase 完成后将这些分支引用一并移动到对应的新提交上，从而避免堆叠分支在 base 变更后仍指向旧历史。但 Git 出于安全考虑，不会自动移动当前在任何 worktree 中检出的分支——因为移动引用会导致该工作树的 HEAD 与工作区内容不一致。这正是文档中"在 worktree 中检出的分支不会以这种方式更新"的含义，也是并行代理场景下需要额外处理堆叠任务的原因。

worktree的创建与清理

worktree.guessRemote

如果代理在另一台机器推送了fix-login，而你想在本地worktree中检出它，直接git worktree add ../fix-login会从当前HEAD新建同名分支，完全不包含代理的提交。worktree.guessRemote会让Git寻找"与新分支名唯一匹配"的远程追踪分支并检出、设置上游。注意它是按文件夹basename匹配的，所以hermes/fix-login这种带斜杠的名字匹配不到，需要显式指定分支名。

清理失效记录

用rm -rf删除worktree文件夹而非git worktree remove，会在.git/worktrees留下管理文件，git worktree list仍会显示并标记为prunable。默认git gc执行git worktree prune --expire 3.months.ago，这些记录要留三个月。把gc.worktreePruneExpire设为更短的期限可以更快清理。修剪只删除Git的记录，从不删除实际文件。对于挂载在移动硬盘上的worktree，可以用git worktree lock加锁防止误清理，锁同时会阻止move和remove操作。

git worktree prune 清理的是 .git/worktrees/ 下的管理目录，而非工作树中的实际文件。每个 worktree 在 .git/worktrees/<name>/ 下有一个包含 gitdir 指针的目录，当工作树文件夹被手动删除后，该指针失效，对应记录即成为 "prunable"。--expire 参数用于设置过期阈值，只清理最后修改时间早于该阈值的记录，默认由 gc.worktreePruneExpire 控制（三个月）。将 gc.worktreePruneExpire 设为 now 可在每次 git gc 时立即清理所有失效记录，设为 2.weeks.ago 则保留两周缓冲，适合并行代理频繁创建与销毁 worktree 的场景。

一次性配置脚本

以下九项设为全局，第一项在每个仓库单独执行：

git config --global merge.conflictStyle zdiff3
git config --global diff.algorithm histogram
git config --global rerere.enabled true
git config --global push.autoSetupRemote true
git config --global fetch.prune true
git config --global rebase.updateRefs true
git config --global branch.sort -committerdate
git config --global worktree.guessRemote true
git config --global gc.worktreePruneExpire 2.weeks.ago

# 每个仓库
git config extensions.worktreeConfig true

这套配置不依赖特定工具。无论使用Hermes IDE、Claude Code还是其他代理框架，只要代理在worktree中工作，共享配置的问题就存在，上述设置都能生效。Hermes IDE的作者在原文中说明其任务启动时会创建独立的hermes/<name>分支和worktree，这些分支和worktree都是普通Git结构，因此手动diff、rebase、merge时配置照常适用。