Claude Code CLI支持Worktree实现多分支并行独立工作

小溪彼岸
0 阅读7分钟

小伙伴们大家好，我是小溪，见字如面。前面我们了解了Claude Code Agent Teams，通过Claude Code Agent Teams我们可以将一个任务按团队开发模式分饰多角串并行开发，在某种程度上可以极大提高开发效率和质量，但是这种工作模式仍然是建立在单一工作区和单个任务的基础上，如果我们想要并行开发多任务就需要用到另一个功能Worktree了。Claude Code Worktree功能在2025年2月就发布了，一直没有了解和使用过，最近有相关使用场景，记录一下学习和使用过程。

优势

  • 支持多Claude Code实例和多任务并行开发
  • 环境隔离互不影响

限制

  • 总是从远端默认分支签出，指定分支签出需要Git原生命令配合

Claude Code Worktree简介

Worktree 是我们排名第一的生产力技巧。可以运行多达 5 个并行终端实例，外加额外的 Web 会话。

— Boris Cherny，Claude Code Tips from the Creator

Worktree是Claude Code团队每天都在用的功能，Anthropic负责人Boris Cherny称它为"排名第一的生产力技巧"，其主要作用就是：让多个 Agent 能够并行工作而不互相干扰。

Worktree是Git的原生功能，Claude Code 的 --worktree 命令将这个功能封装得更加简单易用，一条命令就能 创建隔离环境、启动Claude实例、完成后自动清理。

技术特点

Claude Code Worktree具有以下特点：

  • 共享数据库：Worktree 共享同一个 .git 数据库，所有的提交历史、分支信息都是共享的。这意味着在一个 worktree 里创建的commit，其他 worktree 立刻可见。
  • 独立文件状态：每个 worktree 维护独立的文件状态，同时共享 git 历史记录，这可以防止 Claude 实例在处理不同任务时相互干扰
  • 自动化管理：相比原生的Git Worktree，Claude Code 的 --worktree命令封装了复杂流程。它能 自动创建隔离环境、启动 Claude 实例，并在任务完成后自动清理。

使用场景

我们日常使用Claude Code的开发模式是以文件目录为工作区，使用Git进行版本控制，这就意味着我们的工作区每次只能有一个工作分支，如果启用多个Claude Code窗口进行开发就会导致代码冲突。现在有了Worktree就可以很好的处理这种使用场景，但是Worktree也不是万能的，在小任务上使用反而浪费时间，因为使用Worktree需要经历 创建环境、安装依赖、开发、合并 等过程，可能比任务本身耗时还久，因此Worktree更适合以下使用场景：

  • 功能解耦：当你有多个互不相关的 Feature 或 Bug 需要同时开发/修复时。
  • 长时任务托管：对于需要运行很久的任务（如大规模重构或跑大型测试），可以开一个 Worktree 让 Claude 慢慢跑，不影响你在主目录继续写代码。
  • 实验性改动：在完全隔离的环境中进行风险较高的尝试，即便写烂了也不会影响主分支的稳定性。

前置条件

在Claude Code CLI中使用Worktree也是有条件限制的，需满足以下条件：

  • Git初始化：必须在已初始化的Git仓库目录中
  • 至少有一个 commit：空仓库无法创建worktree
  • 有远程默认分支：必须有远程默认分支，Claude Code CLI Worktree默认从远程分支检出

基本使用

创建Worktree

首先确保项目已经初始化过Git即项目中包含 .git 目录

Image

在命令行终端输入 git remote show origin 查看远程分支信息

Image

我们可以验证一下Worktree的默认迁出分支是不是默认远程分支，首先基于main分支创建一个dev分支，在本地main分支添加“branch main”标识

Image

在本地dev分支添加“branch dev”标识

Image

接着使用 --worktree 或 -w 参数启动Claude Code CLI

# 创建名为 "feat-home" 的 worktree 并启动 Claude
$ claude -w feat-home

# 自动生成随机名称（如 "curious-marinating-flamingo"）
$ claude -w

分别执行上面命令，启动后可以看到Claude Code在工作区 .claude/worktrees 目录下创建了2个新的工作区目录 eventual-discovering-meadow 和 feat-home

Image

打开Worktree工作区下的README文件可以看到均是未做过修改的，可以排除Worktree的代码是从本地本分支创建的

Image

我们也可以让AI帮我们分析，可以看到AI通过 git log、git merge-base 等信息确认：worktree是基于 origin/main 创建的，而非当前分支

Image

在启动的Claude Code CLI中执行 !pwd 可以看到当前工作区目录已经变成了Worktree工作区目录，已经不再是默认的主工区目录了

Image

Worktree除了创建了工作区目录，还同样创建了Git分支，在Cursor等IDE中可以很直观的看到

Image

从上面验证可以Claude Code CLI Worktree命令主要做了下面 4件 事：

  • 在 .claude/worktrees/ 目录下创建新的工作目录
  • 创建名为 worktree- 的新分支
  • 从远端默认分支（origin/main 或 origin/master）检出代码（不是你当前所在的分支）
  • 在Worktree新目录中启动Claude Code

从特定分支签出

Claude Code Worktree默认是从远端的默认分支签出代码的，如果想从指定分支签出代码，我们可以 通过AI创建 或者使用 Git原生命令创建

通过AI创建

首先在当前分支添加分支标识并提交（没有提交的内容从当前分支签出时无法同步签出）

Image

在当前Claude Code CLI会话中直接让Claude Code创建Worktree

基于当前分支创建一个新的worktree

Image

查看新创建的Worktree工作区中的README文件是包含我们上面添加的分支标识的

Image

Git原生命令创建

Claude Code CLI Worktree是在Git原生命令基础上封装的，所以使用Git命令创建Worktree是可行且更强大的。我们切换到dev分支，在命令行终端执行如下命令基于当前分支创建Worktree

# 基于当前HEAD创建worktree
$ git worktree add -b test-feature .claude/worktrees/test-feature HEAD

创建完成后和Claude Code Worktree创建的效果一致

Image

我们也可以基于特定的分支创建Worktree

# 基于某个特定分支
$ git worktree add -b hotfix-home .claude/worktrees/hotfix-home origin/develop

使用Git命令创建的Worktree，我们可以进入到Worktree工作目录启动Claude Code CLI

$ cd .claude/worktrees/test-feature
$ claude

也可以直接使用 --worktree 参数启动，Claude Code CLI会自动打开 .claude/worktrees/test-feature 工作区

$ claude --worktree test-feature

退出与清理

当我们从Worktree中退出时，Claude Code CLI会提示我们选择保留或删除，需要保留下次继续使用一定要选【Keep worktree】

Image

  • Keep worktree：保留Worktree
  • Remove worktree：删除Worktree及所有文件更改、Commit

我们需要重新启用已存在的Worktree时，可以直接通过下面命令启动

$ claude -w feat-home

代码合并

使用Claude Code Worktree开发并验证完成后，下一步就是要把改动合并到主分支，我们同样可以 通过AI合并 和 手动合并 两种方式来完成。

通过AI合并（推荐）

提交修改内容

Image

在Claude Code CLI会话中

把 worktree-test-feature 分支改动合并到当前分支

如果worktree中某些不想要的commit，可以选择性的cherry-pick

查看 worktree-test-feature 分支所有commit历史，把修改README的commit cherry-pick 到当前分支

该示例中我们修改了 dev 和 worktree-test-feature 中的README文件，在合并时会出现冲突，我只需告诉AI合并规则就行，比如我这里是“保留双方更改”，也可以在IDE中手动进行合并

Image

合并完成后，我们就得到最终合并后的代码，合并后可以看到Cluade Code同时清理了test-feature Worktree工作目录和分支

Image

手动合并

直接在命令行终端输入下面命令进行合并

$ git merge feat-new-feature

Image

或者在IDE中选择【分支】【合并】

Image

与通过AI合并方式不同的是，手动合并Claude Code CLI不会帮我们清理合并后的Worktree和分支，我们需要手动进行清理

Image

使用如下命令清除Worktree

$ git worktree remove .claude/worktrees/feat-new-feature

Hooks

Claude Code Worktree提供了Worktree Hooks，通过定义工作区钩子，非Git用户也能完整体验到代码隔离机制带来的优势。

// .claude/settings.json
{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); WORKTREE_PATH=$(echo \"$INPUT\" | jq -r '.cwd'); echo \"$WORKTREE_PATH\"; echo \"[$(date '+%Y-%m-%d %H:%M:%S')] WorktreeCreate: $(echo \"$INPUT\" | jq -r '.name')\" >> ~/.claude/worktree.log"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); WORKTREE_PATH=$(echo \"$INPUT\" | jq -r '.worktree_path'); echo \"[$(date '+%Y-%m-%d %H:%M:%S')] WorktreeRemove: $WORKTREE_PATH\" >> ~/.claude/worktree.log"
          }
        ]
      }
    ]
  }
}

注意事项

worktree删除失败

Worktree没有被删除时分支是不能被删除的

Image

需要手动使用Git命令或手动删除Worktree

$ git worktree remove .claude/worktrees/feat-new-feature

删除完成后即可删除分支

Image

创建进程卡死

如果出现无法创建Worktree进程卡死的情况，可以检查下是否配置科学上网环境

Image

在命令行终端执行下面命令

$ export https_proxy=http://127.0.0.1:7897 http_proxy=http://127.0.0.1:7897

重新执行即可

Image

友情提示

见原文：Claude Code CLI支持Worktree实现多分支并行独立工作

本文同步自微信公众号 "程序员小溪" ，这里只是同步，想看及时消息请移步我的公众号，不定时更新我的学习经验。友情提示友情提示

avatar
文章
阅读
粉丝