Nethür
登录
macOS 版即将推出

博客 · 2026年11月5日

Claude Code worktree 详解

用平实的语言讲解 Claude Code 中的 git worktree:它们隔离了什么、放在哪里,以及如何在不丢失工作的情况下创建、审查和删除。

示意图:一个 main 分支拆分为三个 Nethür worktree,每个任务一个

Claude Code worktree 就是你运行 Claude Code 的普通 git worktree。git 在另一个 branch 上检出仓库的第二份副本,Claude Code 以该目录作为工作树,而你原来的 checkout 保持不变。位置就是你传给 `git worktree add` 的路径,或者为你自动创建 worktree 的工具所管理的目录。

“Claude Code worktree”听起来像是一个需要开启的功能。多数情况下它更简单:worktree 是 git 创建的目录,Claude Code 是在你启动它的目录中编辑文件的进程。把这两件事放在一起,你就得到了隔离的 agent session。

这个区分很重要,因为网上把三件不同的事混在一起:git worktree、Claude Code 自家应用里的 worktree 功能,以及替你创建 worktree 的工作空间工具。它们共享同一个名字和目的,但位置、清理和审查方式会因目录由谁创建而不同。

git worktree 到底是什么

普通 clone 只有一个工作树:你在编辑器里看到的文件。git worktree 让同一个仓库同时拥有多个工作树,每个工作树位于不同的 branch。对象数据库和 remote 是共享的;检出的文件和 index 则不共享。换句话说,磁盘上多了一份文件,仓库的历史并没有多出一份。

git worktree list
# /Users/you/app             abc1234 [main]
# /Users/you/app-fix-login   def5678 [fix/login]
  • 每个 worktree 都有自己的 branch、HEAD、index 和磁盘上的文件。
  • 不能在两个 worktree 中同时检出同一个 branch。
  • 删除 worktree 会移除目录及其 checkout,但不会删除 branch 历史。
  • 每个 worktree 仍然属于同一个仓库,因此 commit、fetch 和 push 看到的是同一批对象。

这正是 agent 需要的隔离。Claude Code 可以在自己的 worktree 中读取、编辑、运行测试和 commit,而不会碰到你打开着的 checkout。如果 agent 搞坏了什么,删掉那个目录,你的主 branch 依然完好。

为什么 Claude Code 受益于 worktree

agent session 不是那种偶尔碰一下文件的聊天。它会运行命令、启动 dev server、写生成文件、暂存改动,有时还会切换 branch。同一个 checkout 中的两个 session 共享所有这些状态。这些动作单独看都很普通,叠在一起就会互相影响。故障很少戏剧化:测试针对错误的代码通过了、formatter 重写了另一个 agent 的工作,或者一次 commit 把两个任务的文件都带了进去。

worktree 把这些共享状态导致的故障变成了彼此独立的目录。一个目录出问题,不会顺带污染另一个目录。代价是每个新 worktree 都从干净状态开始:没有 node_modules、没有 .env、没有本地数据库。本文余下的内容,主要就是在讲如何有意识地支付这个代价。

Claude Code 有 worktree 模式吗?

Claude Code CLI 不需要特殊模式就能在 worktree 中工作。它的 session 边界就是工作目录。在 ../app-fix-login 里启动 claude,session 就在那里读写;在 ../app-fix-billing 里启动另一个,它就有不同的 branch 和不同的文件集合。

Claude Code 的其他界面会替你管理 worktree。桌面应用可以在隔离的 git worktree 中运行并行 session,agent team 或 subagent 可以在 session 内部委派工作。这些都是便利层:它们创建 checkout、把 agent 放进去、把路径隐藏起来。如果你需要可预测的位置,就自己创建 worktree,然后在里面启动 Claude Code。

Claude Code worktree 应该放在哪里?

位置取决于谁创建 worktree。手动搭建时,把路径传给 git worktree add。有两种约定很好用:放在主 checkout 旁边的同级目录,或者放在仓库外一个专门的 worktrees/ 文件夹。

# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main

# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/main

把 worktree 放在主 checkout 之外。放在仓库内部的 worktree 会出现在每次搜索里、干扰编辑器索引,还可能被误提交。如果某个工具在仓库内的隐藏文件夹里创建 worktree,先确认该文件夹是否已被 gitignore,再决定是否依赖它。

Nethür 在自己的管理目录中创建 worktree,并替你跟踪路径。如果你已经有 Claude Code、GSD 或直接用 git worktree add 创建的 worktree,Nethür 可以把它们作为外部 worktree 展示,而不要求你迁移。Settings → General → Workspace 控制显示哪些外部来源,以及扫描哪些位置根目录。

如果你不想手动管理路径,像 Nethür 这样的 git worktree 图形界面可以替你创建、跟踪和清理 worktree,同时仍在磁盘上保留一个普通的 checkout。

创建一个 worktree 并启动 Claude Code

从一个最新的 base ref 开始,免得 agent 对着上周的代码工作。

git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claude

给每个 worktree 用唯一的 branch 名。如果你想在同一个任务上再加一个 agent,就创建第二个 worktree 并换一个 branch,哪怕 prompt 完全相同。branch 正是让两个结果可以独立比较、独立 merge 的前提。

在 Nethür 里,同样的步骤就是一个对话框:创建 worktree、给任务命名、选择 start-from ref、选择 agent。Nethür 在后台执行 git fetch 和 git worktree add,创建过程中就展示工作空间,并在新的 checkout 中打开 agent。worktree 文档介绍了 start-from 选择器、文件夹工作空间和关联 issue。

依赖、env 文件和端口

全新的 worktree 是干净的 checkout,这意味着它缺少所有被 git 忽略的东西。有三种处理方式,多数团队最后三种都会用上。

  • 每个 worktree 单独安装。正确且简单,但当每个 agent 都需要自己的 node_modules 时,又慢又占磁盘。
  • 共享体积大、可重建的目录。Nethür 的 Worktree Shared Paths 会从主 checkout 物化被 gitignore 的目录,仓库级定义写在 nethur.yaml 的 worktree.sharedDirectories 中。
  • 复制体积小、因 worktree 而异的文件。.worktreeinclude 列出要复制的被 gitignore 的文件和目录,例如 .env 或本地编辑器设置,让每个 worktree 拥有自己的副本。
# nethur.yaml at the repo root
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.json

端口值得单独定规则。如果两个 agent 启动同一个 dev server,第二个要么失败,要么更糟——连上了第一个的数据库。把端口和数据库名放进每个 worktree 的环境文件,或者让 setup hook 根据 worktree 名称推导出来。

审查 diff,然后删除 worktree

针对 worktree 起始时的 ref 审查每个 worktree,而不是针对当前 main 上碰巧存在的状态。这样 diff 才能聚焦在 agent 的工作上。Nethür 按工作空间展示 diff,支持行内标注,并且可以在你 commit 之前把审查意见发回给 agent。

工作 merge 之后,删除 worktree 和 branch。不要手动删目录:git 在 .git/worktrees 下维护元数据,手动 rm -rf 会留下过期条目。

git worktree remove ../app-fix-login
git branch -d fix/login

# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-login

即使 worktree 已经不在了,git 仍可能保留包含未 merge commit 的本地 branch。这是安全网,不是 bug。Nethür 会在审查步骤中展示被保留的 branch,让你决定哪些强制删除,而不用事后到处翻找。

常见的 worktree 错误

  • 在两个 worktree 中检出同一个 branch。git 会拒绝;给第二个 agent 换一个 branch。
  • 把 worktree 放在仓库内部。搜索和编辑器会看到重复文件,而且该目录可能被提交。
  • 共用一个指向主数据库的 .env。涉及 migration 时,每个 agent 都应该有自己的数据库或 schema。
  • 忘记 base ref。从过期的本地 branch 创建 worktree,会产生令人困惑的 diff 和痛苦的 merge。
  • 实验结束后留下几十个打开的 worktree。趁你还记得哪个赢了,把 branch 清理掉。

团队中的 worktree

在团队服务器上,worktree 不再是私有目录。它们是共享的项目状态:队友能看到某个 worktree 存在、由谁创建、正在运行哪个 agent,以及它是否被阻塞。正是这种可见性让交接工作变得安全。

无论运行在你的笔记本、队友的机器、VPS 还是 SSH 目标上,Nethür 都保持同一套 worktree 模型。agent 在 checkout 所在的地方运行,客户端只负责渲染 session。如果你想要这套设置的团队版本,请阅读面向团队的 Claude Code。

先在一个任务上试试

为一个小改动创建一个 worktree,在里面启动 Claude Code,并让主 checkout 保持打开、放在旁边。一旦你看到两个 session 不再互相干扰,那个多出来的目录就不再像负担了。并行 agent 指南展示了如何把它扩展到多个 agent 并比较结果。

把指南用起来。

下载 Nethür,几分钟内跑起第一个并行 agent;或者在你已有的机器上搭建团队工作空间。