git worktree 实用指南：让多个 AI agent 并行干活

git worktree 是什么？

普通的 clone 只有一个工作目录：你看到的文件，加上一个 HEAD 和一个暂存区（index）。worktree 是挂在同一个仓库上的额外工作目录。每个 worktree 有自己的 HEAD、暂存区和文件，但共用同一个对象库、同一套分支和标签、同一份配置。

也就是说，你可以让 ~/code/app 停在 main，~/code/app-search 做新功能，~/code/app-fix-login 修 bug，三者同时打开，不用 stash，也不用来回切分支。

为什么有了 AI 编码 agent 之后，worktree 更重要了

Claude Code、Codex、Gemini CLI 这类 agent 会直接改文件。两个 agent 放在同一个目录里，会互相覆盖改动，还会抢 .git/index.lock。分别 clone 也行，但每份都要下载完整历史，而且很快就和远端脱节。worktree 介于两者之间：每个 agent 有自己的目录和分支，而一个目录里提交的 commit，其他目录马上就能看到，因为仓库是同一个。

真正用得上的 5 条命令

其余所有子命令和参数都在 git worktree 速查表里。

在新分支上建 worktree

git worktree add -b feat/search ../app-search main

这条命令会创建 ../app-search 目录，从 main 新建 feat/search 分支并检出到那里。

为已有分支建 worktree

git worktree add ../app-fix-login fix/login

列出所有 worktree

git worktree list

显示每个目录、所在的 commit 和分支。它不会告诉你这个分支合并了没有、push 了没有、有没有没提交的改动，后面会讲到。

删除 worktree

git worktree remove ../app-search

如果目录里有修改过的或未跟踪的文件，git 会拒绝。加 --force 会跳过检查，这些文件就永久删掉了。分支本身不会被删，需要另外用 git branch -d。

手动删了目录之后的清理

git worktree prune

如果你用 rm -rf 或访达直接删了 worktree 目录，git 仍会在 .git/worktrees/ 里保留记录，并认为那个分支还被检出着。prune 会清掉这些过期记录。

拿不准该用 worktree 还是只建个分支？看 git worktree 和 branch 的区别。

值得提前知道的坑

• 一个分支只能在一个 worktree 里。同一分支同时只能检出到一个 worktree，在别处再检出会报错，并告诉你它已经被哪个 worktree 占用。
• 被 ignore 的文件不会跟过来。新 worktree 只有被跟踪的文件。.env、node_modules、构建产物都要在每个 worktree 里重新复制或安装。
• stash 是共享的。在任何一个 worktree 里执行 git stash list 看到的都是同一份列表，很容易 pop 到别人的 stash。
• 依赖和端口。每个 worktree 都要单独安装依赖，两个开发服务器也不能用同一个端口。
• 越积越多。并行跑一周 agent，很容易攒下十几个 worktree：有的已经合并，有的有没 push 的 commit，有的有没人提交的改动。

worktree 多了以后怎么管

最后一个坑最容易丢工作。git worktree list 回答的是“它们在哪”，而不是“哪些还重要”。要判断一个 worktree 能不能删，得逐个检查有没有未提交改动、未跟踪文件、没 push 的 commit、stash，以及分支是否已经进了 main（包括 squash 合并）。如何安全清理 git worktree 这篇文章讲了怎么手动做这些检查。

Orchard 会持续为你 Mac 上每个项目的每个 worktree 做这些检查，显示哪个 AI agent 在哪个目录工作，并给出每个结论的依据，比如“PR #142 已于 3 天前合并”。

常见问题