一个项目里跑一个 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。用
git --version检查。 - 一个至少有一次提交的仓库。
- 一个可以从终端启动的编程智能体。
- 足够的磁盘空间,用来存放项目文件和依赖的第二份(或第三份)副本。
示例使用名为 my-app 的项目文件夹和 main 分支。请换成你自己的名称。

第 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.
两个习惯能让并行工作更顺畅:
- 按区域拆分任务。两个智能体改写同一个文件,之后必然产生合并冲突。请选择涉及代码不同部分的任务。
- 把共享规则放进受跟踪的文件。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 日。





写评论