什么是 Git Worktree？

worktree 解决了什么问题

一个文件夹只能检出一个分支。worktree 会再加一个文件夹，检出另一个分支。

通常，一个仓库就是一个文件夹，一次只检出一个分支。要同时做两件事，你得先 stash 修改，切换分支，做完另一件事，再切回来并恢复 stash。这样能行，但很慢，也容易出错。

有了 worktree，你会得到第二个文件夹，而且它已经在另一个分支上。功能 A 在一个文件夹里，功能 B 在另一个文件夹里，两个同时打开，不用 stash，也不用切换。

为什么 AI 智能体需要它

正是 worktree 让在一个仓库上运行多个智能体变得安全。

两个 AI 智能体在同一个文件夹里会覆盖彼此的修改。智能体 A 编辑 auth.ts，一分钟后智能体 B 编辑 auth.ts，谁最后保存谁就赢。另一个智能体的工作就没了，而且它们俩都不知道。

每个智能体各用一个 worktree，就各有自己的文件夹、分支和文件。两个智能体可以同时编辑 auth.ts，互不影响对方的副本。完成后，你再分别审查和合并每个分支。

磁盘上的目录结构

历史相同，文件分开。文件夹放在哪里由你或你的工具决定。

my-project/                 ← your main checkout (main)
my-project/worktrees/
  ├─ add-auth/              ← worktree, branch add-auth
  └─ fix-nav/               ← worktree, branch fix-nav

所有 worktree 共用同一份 git 历史，所以在一个 worktree 里做的提交，在其他 worktree 里也能看到。未提交的修改留在各自的文件夹里。Git 本身并不在乎 worktree 放在哪里：可以在仓库旁边、在单独的文件夹里，也可以像 Pane 那样放在仓库内部。

Pane 如何自动管理 worktree

Pane 会为每个 pane 创建、填充并清理 worktree，所以你永远不用输入这些命令。

你不用运行任何 git 命令。创建 pane 时，Pane 会：

1. 取用它为该项目和分支预先准备好的 worktree，所以 pane 几乎瞬间打开，并给它一个新分支。
2. 把你的 .env 文件、.claude 和 .codex 这类智能体设置，以及 node_modules 复制进去，让智能体马上就能开始。你可以在设置中修改这个列表。
3. 归档 pane 时，先检查有没有未提交、未跟踪或未推送的工作，然后删除 worktree。归档的 pane 之后还可以恢复。

手动方式

三条命令用来创建和启动，两条用来清理。

不用工具的话，同样的事情需要几条 git 命令：

echo "worktrees/" >> .git/info/exclude   # once: keep them out of git status
git worktree add worktrees/add-auth -b add-auth
cd worktrees/add-auth
claude                      # start your agent here

# once the branch is merged:
git worktree remove worktrees/add-auth
git branch -d add-auth

合并后记得删除 worktree 和分支。大多数人都会忘，这就是工具要把它自动化的原因。

相关文档

• → Pane 与 Worktree，Pane 如何管理 worktree
• → 并行运行智能体，完整的并行工作流
• → Monorepo，如何在 monorepo 中使用 worktree
• → 适合 AI 智能体的 Git Worktree，落地页概览

来源

勘误

如果这里有任何错误或过时的内容，请告诉我们，我们会修正并更新顶部的日期。 在 GitHub 上提交 issue

来源

• → git-worktree documentation
• → Panes & Worktrees (Pane docs)
• → Git worktree tools for AI agents