如何用 Git worktree 并行运行多个 AI 编程智能体

用 Git worktree 给每个 AI 编程智能体分配独立的文件夹和分支,然后审查、合并并清理。附可直接复制的命令和常见错误的解决方法。

Graphic of a tree with three branches, each holding a folder and a small robot at a terminal, for a guide to Git worktrees with AI coding agents

一个项目里跑一个 AI 编程智能体很简单。同一个文件夹里跑两个就乱套了:它们会改同一批文件,共用一个检出的分支,还会互相覆盖对方的成果。Git worktree 正是内置的解决办法。本指南教你用它让多个智能体并排工作,各自在自己的分支上,最后再审查并合并结果。

要点速览

  • Git worktree 是一个额外的工作文件夹,拥有自己的文件和分支,并与仓库共享同一份历史。
  • 用 git worktree add -b 为每个任务创建一个 worktree 和一个新分支,然后复制 .env 并重新安装依赖。
  • 在每个 worktree 中启动一个独立的智能体,给它分配代码中不同区域的一个明确小任务。
  • 合并前用 git log 和 git diff 审查每个分支,然后删除 worktree 和已合并的分支。

这个方法适用于任何在终端里运行的编程智能体。下面的每条 Git 命令都在 Git 2.53 上运行过,并对照了官方 git-worktree 文档(最近一次更新针对 Git 2.56)。

为什么智能体需要各自的文件夹

Git worktree 是挂接在同一个仓库上的额外工作文件夹。每个 worktree 都有自己的文件和自己检出的分支,但它们共享同一份历史。用 Git 自己的话说,关联的 worktree 共享“除 HEAD、index 等每个 worktree 专属文件之外的一切”。

所有 worktree 共享每个 worktree 独立
提交和历史磁盘上的文件
分支和标签当前检出的分支(HEAD)
仓库配置暂存区(index)
未跟踪和被忽略的文件,例如 .env 或 node_modules

这种划分正是并行智能体所需要的:文件彼此隔离,又有一份共享历史可供合并。

现在已有好几款工具内置了这个功能。Cursor 可以把每个智能体放进各自的 worktree,Codex 可以在某个 worktree 中开启对话,Claude Code 则提供 --worktree 参数。手动操作只需几条命令,适用于所有智能体,还能让你看清这些功能在底层做了什么。

对比图:Git worktree 共享的内容(如历史和分支)与各自独立保留的内容

准备工作

  • Git。用 git --version 检查。
  • 一个至少有一次提交的仓库。
  • 一个可以从终端启动的编程智能体。
  • 足够的磁盘空间,用来存放项目文件和依赖的第二份(或第三份)副本。

示例使用名为 my-app 的项目文件夹和 main 分支。请换成你自己的名称。

流程图:用 Git worktree 并行运行多个 AI 编程智能体的五个步骤

第 1 步:从干净的 main 分支开始

新的 worktree 从你当前的提交开始,所以请先提交或 stash 未完成的工作。在项目文件夹中执行:

终端
git status --short

没有输出说明文件夹是干净的。

第 2 步:每个任务创建一个 worktree

给每个任务分配独立的文件夹和新分支。这里有两个任务:修复登录问题和新增搜索功能:

终端
git worktree add -b fix-login ../my-app-login
git worktree add -b add-search ../my-app-search

第一条命令的预期输出:

代码
Preparing worktree (new branch 'fix-login')
HEAD is now at 61730c6 Initial commit

-b fix-login 会创建一个新分支,../my-app-login 是新文件夹的位置:放在项目旁边,而不是项目里面。检查结果:

终端
git worktree list
代码
/home/user/code/my-app        61730c6 [main]
/home/user/code/my-app-login  61730c6 [fix-login]
/home/user/code/my-app-search 61730c6 [add-search]

第 3 步:配置每个 worktree

新的 worktree 是一次全新的检出。它只包含 Git 跟踪的文件,所以 .gitignore 中列出的内容都不在里面:环境文件、已安装的包、构建产物。把项目运行所需的东西复制过来或重新生成。比如项目使用 .env 文件时:

代码
cp .env ../my-app-login/.env
cp .env ../my-app-search/.env

然后在每个 worktree 中用你平常的命令安装依赖(npm ci、uv sync 等)。Cursor 的文档建议不要用符号链接把依赖链接进 worktree,因为这可能导致主文件夹出问题。请老老实实地正常安装。

如果项目会启动开发服务器,请给每个 worktree 分配不同的端口,以免智能体的服务器互相冲突。

你知道吗?

新的 worktree 只包含 Git 跟踪的文件,所以 .gitignore 中的内容,例如 .env 文件和已安装的包,在你复制或重新安装之前都是缺失的。

第 4 步:每个 worktree 启动一个智能体

为每个 worktree 单独打开一个终端标签页或窗口,进入对应文件夹,然后像平常一样启动智能体。以开源的 Qwen Code 为例:

终端
cd ../my-app-login
qwen

在第二个标签页中对 ../my-app-search 做同样的操作。现在每个智能体都在自己的文件夹、自己的分支上工作。

给每个智能体一个范围明确、终点清晰的任务。一个效果不错的提示词:

代码
Fix the login bug where a wrong password shows a blank page.
Only change files needed for this fix. Run the tests, and when
they pass, commit your work to the current branch.

两个习惯能让并行工作更顺畅:

  1. 按区域拆分任务。两个智能体改写同一个文件,之后必然产生合并冲突。请选择涉及代码不同部分的任务。
  2. 把共享规则放进受跟踪的文件。AGENTS.md 是一种向编程智能体提供指令的开放格式(安装命令、测试命令、代码风格)。把它提交到仓库,每个新的 worktree 都会自动获得一份副本。我们的 Claude Code 智能体技能(agent skills)指南介绍了另一种相关的指令打包方式。

第 5 步:审查每个分支

不必离开主文件夹就能查看智能体做了什么。git -C <path> 会像你身处那个文件夹一样执行命令:

终端
git -C ../my-app-search status --short
代码
?? scratch.txt

这里显示了一个智能体创建了却没有提交的遗留文件。现在就提交或删除这类遗留文件,因为只要还有它们,Git 就会拒绝删除 worktree。要查看某个分支在 main 之上新增的提交和改动:

终端
git log --oneline main..fix-login
git diff --stat main...fix-login
代码
873a385 Fix login
 app.py | 1 +
 1 file changed, 1 insertion(+)

去掉 --stat 即可查看完整 diff。请认真阅读:智能体说“完成了”并不能证明改动是对的。如果项目是网站,具备浏览器访问能力的智能体可以自行检查成果,详见我们的 Chrome DevTools MCP 指南。

第 6 步:合并并清理

在主文件夹中合并每个已完成的分支:

终端
git merge fix-login
git merge --no-edit add-search
代码
Updating 61730c6..873a385
Fast-forward
 app.py | 1 +
 1 file changed, 1 insertion(+)
Merge made by the 'ort' strategy.
 search.py | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 search.py

如果你在团队中工作,请推送每个分支并发起 pull request,而不是在本地合并。我们的 SSH 密钥指南介绍了如何免密码访问远程服务器。

然后删除 worktree 和已合并的分支:

终端
git worktree remove ../my-app-login
git worktree remove ../my-app-search
git branch -d fix-login add-search

git worktree remove 会删除整个文件夹,包括其中被忽略的文件,例如复制过去的 .env。再次运行 git worktree list,应该只剩下你的主文件夹。

你知道吗?

git worktree remove 会删除整个文件夹,包括复制过去的 .env 等被忽略的文件;如果 worktree 里还有未提交的遗留文件,Git 会拒绝删除。

可选:一个辅助脚本

熟悉流程后,一个简短的脚本能帮你少打很多字。把下面的内容保存为项目中的 new-task.sh,用 chmod +x new-task.sh 赋予执行权限,然后提交:

代码
#!/usr/bin/env bash
set -euo pipefail

name="$1"
root="$(git rev-parse --show-toplevel)"
dir="$(dirname "$root")/$(basename "$root")-$name"

git worktree add -b "$name" "$dir"
if [ -f "$root/.env" ]; then
  cp "$root/.env" "$dir/.env"
fi
echo "Ready: $dir"

运行 ./new-task.sh try-cache 会在同级文件夹中创建 try-cache 分支,复制 .env,并输出类似下面的内容:

代码
Preparing worktree (new branch 'try-cache')
HEAD is now at 8bca3c4 Merge branch 'add-search'
Ready: /home/user/code/my-app-try-cache

常见错误及解决方法

  • fatal: 'fix-login' is already used by worktree at '...':一个分支同一时间只能在一个 worktree 中检出。请在已经检出它的文件夹中工作,或用 -b 创建新分支。
  • fatal: '../my-app-search' contains modified or untracked files, use --force to delete it:智能体留下了未提交的工作。提交或删除这些文件;如果确定里面没有重要内容,也可以运行 git worktree remove --force ../my-app-search。
  • error: cannot delete branch 'add-search' used by worktree at '...':先删除 worktree,再删除分支。
  • error: the branch 'add-search' is not fully merged:git branch -d 会保护尚未合并的工作。请先合并该分支,或用 git branch -D add-search 放弃这些工作。
  • git worktree list 显示某个文件夹被标记为 prunable:该文件夹是手动删除的,而不是用 git worktree remove 删除的。运行 git worktree prune 清除这条过期记录。
  • 应用在 worktree 中无法启动:被忽略的文件没有复制过去。在那里重新创建 .env 并重新安装依赖(第 3 步)。
  • 第 6 步出现合并冲突:两个智能体改了同样的代码行。手动解决冲突,或运行 git merge --abort,再让其中一个智能体基于更新后的 main 重做它的工作。
  • 移动或重命名主文件夹后出现 fatal: not a git repository: .../.git/worktrees/my-app-login:在主文件夹的新位置运行 git worktree repair。
  • 项目使用了子模块:Git 文档指出,worktree 对子模块的支持并不完整,不建议对这类项目进行多次检出。

总结

worktree 把“一次一个智能体”变成了一支小团队:每个任务一个文件夹、一个分支,用 git diff 快速审查,然后合并并清理。先从两个智能体处理互不相关的任务开始,提示词范围要窄,合并前务必检查 diff。

常见问题

什么是 Git worktree?

挂接在同一个仓库上的额外工作文件夹。每个 worktree 都有自己的磁盘文件、检出分支和暂存区,而所有 worktree 共享同一份提交历史、分支、标签和仓库配置。

两个 worktree 能使用同一个分支吗?

不能。一个分支同一时间只能在一个 worktree 中检出,Git 会用 already used by worktree 错误阻止你。请在已检出该分支的文件夹中工作,或用 -b 创建新分支。

为什么我的应用在新的 worktree 中无法启动?

新的 worktree 只包含 Git 跟踪的文件,因此 .env 等被忽略的文件和已安装的包都不在里面。把 .env 复制过去,再用你平常的命令在该 worktree 中重新安装依赖。

如何安全地删除 Git worktree?

先提交或删除遗留文件,然后带上文件夹路径运行 git worktree remove,再用 git branch -d 删除已合并的分支。如果你是手动删除的文件夹,运行 git worktree prune 即可清除过期记录。

小测验

关联的 worktree 与主文件夹共享什么?

  • 它的暂存区
  • 提交历史
  • 它检出的分支

worktree 共享同一份历史,但每个都有自己的文件、检出分支和 index。

文件夹被手动删除后,用哪条命令清理对应的 worktree?

  • git worktree prune
  • git branch -D
  • git merge –abort

运行 git worktree prune 可以清除 git worktree list 标记为 prunable 的过期记录。

为什么并行的智能体应该处理代码的不同区域?

  • worktree 之间不能共享文件
  • Git 限制了每个仓库的智能体数量
  • 编辑同一个文件会导致合并冲突

本指南提醒,两个智能体改写同一个文件,之后必然产生合并冲突。

资料来源

链接最后检查于 2026 年 11 月 15 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。