> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Claude Code原生Git Worktree
- URL: https://www.hubwiz.com/blog/claude-code-native-git-worktree/
- Published: 2026-03-01T11:50:10.000Z
- Updated: 2026-03-01T11:50:10.000Z
- Description: 这感觉像魔法，我现在可以并行运行多个代理而不必担心它们互相踩脚。
- Author: admin
- Tags: AGENT, CLAUDE CODE, #Import 2026-10-14 14:41

这感觉像魔法，我现在可以并行运行多个代理而不必担心它们互相踩脚。

忘记合并冲突和阻塞功能的噩梦；你不再需要等待一个分支稳定后再开始另一个。

我在它发布后立即进行了测试，我想带你了解它是如何工作的以及你今天如何设置它。

但首先，你需要理解 Claude Code 的原生 Git worktree 解决什么问题。

## 1、一次运行一个代理的问题

在工作树之前，如果你同时构建多个功能，你有两个选择。

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-jg-ZPegHEAXWGInp1k-BYg.png)

- 第一种是将所有内容倾倒到一个提示词中。"添加暗黑模式、设置本地存储持久化并添加内联编辑。"Claude 会开始工作，如果这三件事中的任何一件事有 bug，你的整个分支将被阻塞。
- 第二种选择是手动管理单独的分支；创建分支、切换上下文、开始新会话、失去你的流程、重复。这不是你期望的代理工作流的流畅并行体验***。***

如果你经历过这个问题，你会理解随着项目的变大情况会变得更糟。

另一个担忧是在现实世界的项目管理中；功能不会彼此等待。

> **示例：常见的情况是你在调试一件事的同时构建另一件事，并审查第三件事。**你的代理不应该在单文件或单分支车道中工作。

这就是问题，Claude Code 原生 Git worktree 解决了。

## 2、什么是 Git Worktree？

在我们进入 Claude Code 端的东西之前，让我给你一个关于 worktree 是什么的基本知识 —— 因为名称经常令人困惑。

> git worktree 不是单独的仓库。它是链接到同一仓库的单独工作目录。每个 worktree 都有自己的签出分支、自己的 HEAD 和自己的工作文件 —— 但它们都共享相同的 git 历史和对象。

更简单的例子：

- 你的主项目文件夹是办公室里的办公桌
- Worktree 是同一个办公室里的第二张办公桌

> 两张办公桌都有自己的纸张和工具，但它们都从同一个文件柜里拉取。

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-pj0NGoggBeNcVYkLqMZ5QA.png)

对于 Claude Code，这意味着每个代理都在自己的隔离环境中工作。

- 一个代理正在 `feature/auth` 上构建你的身份验证功能
- 另一个正在 `fix/payment-bug` 上修复错误

它们不接触相同的文件，也不等待彼此。

开始之前需要知道的关键事项：

- 你的项目必须初始化 git（`git init`）
- 在 worktree 工作之前，你需要在主分支上至少有一个提交
- 每个 worktree 签出一个唯一的分支 —— 两个 worktree 不能同时共享同一个分支
- 当你完成后，你可以保留 worktree 或删除它。

这是基本的 Git worktree 核心概念，但在 Claude Code 中，它被包装成一个标志，因此你不必手动管理它。你可以从官方[文档](https://git-scm.com/docs/git-worktree?ref=hubwiz.com)了解更多关于 Git worktree 的信息

## 3、入门：Claude --worktree 标志

Claude Code v2.1.50 引入了带有一个标志的原生 worktree 支持。以下是如何使用它。

在使用任何这些工作之前，请确保：

- 你的项目已经初始化了 git（`git init`）—— 让我们检查我们的仓库是否已初始化，使用这个：

```
git log --oneline

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-eie9YKxeaZXcuDH9dqOfCw.gif)

> **你在主分支上至少有一个提交**

- 你在 Claude Code v2.1.50 或更高版本（运行 `claude update` 以检查）

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-a8pZPdstWWULRwzrgay2vQ.gif)

### 3.1 启动 Worktree 会话

要在其自己的 worktree 中启动 Claude Code，添加 `--worktree` 标志（或简写 `-w`）：

```
claude --worktree

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-Xn_4QTmVw6LmdHM7UT0R1Q.gif)

这会使用 Claude 选择的随机分支名称启动一个新的 worktree。它有效，但如果你一次运行多个 worktree，随机名称很快会变得混乱。

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-VlzZg75mi6KlPpw9NxHWZg.png)

Claude Code 想出了这个名字：dreamy-puzzling-codd，你可以看到它创建了一个 worktrees 目录

更好的方法是为你的 worktree 命名：

```
claude --worktree feature/dark-mode

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-COZhMU7Jo0REj5QIVo_-og.gif)

这会创建一个新的 worktree，签出一个名为 `feature/dark-mode`的分支，并在其中启动一个 Claude 会话 —— 全部在一个命令中！

### **3.2 你的 Worktree 位于哪里**

Claude 在你的项目下将 worktree 存储在：

```
.claude/worktrees/feature-dark-mode/

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-vEiha3rmXlcsRgPJyTm-Qw.gif)

你会在那里找到完整的、限定到该分支的工作文件集。你的主分支未受影响。

要确认当前激活了哪些 worktree，运行：

```
git worktree list

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-ZBSN5CITj3K-0x8lusinLw.gif)

你会看到你的主 worktree 和每个链接的 worktree 以及它们的路径和分支名称。

### **3.3 导航到 Worktree 目录**

如果你想直接从 worktree 的目录工作而不是从项目根目录，你有两个选项。

手动导航：

```
cd .claude/worktrees/feature-dark-mode

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-l3X55Uvl4uzhrCNwNXe-AQ.gif)

或者使用 `--dir` 标志在启动时，它会直接带你到那里：

```
claude --worktree feature/dark-mode --dir

```

### **3.4 恢复 Worktree 会话**

我真的很喜欢的一件事 —— 如果你关闭一个会话并在稍后回来，你可以通过指定相同的名称从你离开的地方恢复：

```
claude --worktree feature/dark-mode

```

Claude 会为该 worktree 拾取会话。

你也可以按 `Ctrl+W` 在 Claude Code 内部查看项目中的所有会话并在它们之间跳转。

### **3.5 完成后清理**

一旦功能被合并或你不再需要 worktree，删除它：

```
git worktree remove .claude/worktrees/feature-dark-mode

```

或者如果 worktree 有未跟踪的更改并且你想强制删除它：

```
git worktree remove --force .claude/worktrees/feature-dark-mode

```

请记住 —— 如果你创建了很多临时 worktree 而不清理它们，它们会在 `.claude/worktrees/` 下堆积。养成合并后修剪的习惯。

```
git worktree prune

```

## 4、在并行 Git Worktree 中运行子代理

Worktree 不仅为单个 Claude 会话工作；***子代理也支持它们。***

与其让一个代理在同一分支上处理多个功能，你可以拥有专用子代理在各自的分支上同时工作，每个都在自己隔离的 worktree 中。

### 4.1 触发并行子代理

从你的主 Claude 会话，你可以指示 Claude 像这样通过 worktree 隔离启动子代理：

```
使用 worktree 为你的代理。并行构建 feature/dark-mode、
feature/local-storage 和 feature/edit-todos —— 
每个都在自己的分支上。确保每个代理在打开 PR 之前测试其更改 
结束。

```

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-E1-iqk064zVH4bIoJ8QQ2A.gif)

Claude 将启动三个子代理，每个都在自己的 worktree 中，每个都在自己的分支上，全部同时运行。

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-kb9nhO1dB4obzZj8MP2Kyg.png)

当一个完成时，你可以独立合并或审查它，而不必等待其他的。

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-XGNGOkhtV7oMI0ZPdpOF8A.gif)

> **这是以前需要手动分支管理和多个终端会话的工作流。**

### **4.2 使用 Worktree 隔离配置自定义代理**

如果你在项目中定义了自定义子代理，你可以通过向代理的前面添加 `isolation: worktree` 来使 worktree 隔离自动化。

在 `.claude/agents/your-agent.md` 创建或编辑你的代理文件：

```
---
name: feature-builder
model: claude-sonnet-4-6
isolation: worktree
---
你是一个功能开发专家。当分配功能时，
完全构建它，编写测试并验证它工作后再完成。
始终在小的、集中的提交中工作。

```

> **使用** **`isolation: worktree`** **设置，每次调用此代理时，它自动获得自己的 worktree —— 不需要标志，不需要手动设置。Claude 处理它。**

### 4.3 查看所有活动会话

当你有多个 worktree 运行时，在任何 Claude Code 会话中按 `Ctrl+W` 查看项目中每个活动会话。

> **这会给你一个快速概览，了解每个代理正在做什么，并让你在它们之间跳转。**

### **4.4 使用桌面应用**

如果你不想使用终端，Claude Desktop 应用也支持 worktree 模式。

> **前往代码选项卡，你会看到一个在开始会话之前可以启用的 worktree 复选框。**

![Claude Code Git Worktree](https://www.hubwiz.com/blog/content/images/2026/03/1-1sA3VIUzsfJuNQtrVUlLYg.gif)

> **这是相同的功能，只是带有 GUI —— 如果你在终端和桌面应用之间上下文切换，这很有用。**

## 5、非 Git 项目的 Worktree

如果你的项目使用 SVN 或 Mercurial，你仍然可以通过在 `.claude/settings.json` 中定义的钩子获得 worktree 风格的隔离：

```
{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "jj workspace add \"$(cat /dev/stdin | jq -r '.name')\""
      }
    ],
    "WorktreeRemove": [
      {
        "command": "jj workspace forget \"$(cat /dev/stdin | jq -r '.worktree_path')\""
      }
    ]
  }
}

```

这告诉 Claude 在创建或删除 worktree 时运行你的版本控制的工作区命令。

## 6、结束语

Claude Code 的原生 Git Worktrees 是一个令人印象深刻的功能，适合正确的使用场景。

- **大型代码库迁移** *—* [Boris Cherny（Claude Code 的创建者）](https://x.com/bcherny/status/2025007393290272904?ref=hubwiz.com) *提到使用数百个并行代理进行大规模同步到异步迁移，每个代理处理一个文件夹并打开自己的 PR。*
- **独立功能** *— 当你的任务不共享文件或不依赖于彼此时，并行 worktree 消除了所有等待。*
- **活动开发期间的错误修复** *— 在一个 worktree 中修复生产错误，同时在另一个中继续构建，而没有任何分支污染。*
- **代码审查** *— 启动一个 worktree 来审查 PR，而不会干扰你当前的工作分支。*

如果你一次构建多个活动功能，这值得今天添加到你的工作流中。

---

原文链接: [I Tried (New) Claude Code Git Worktree (I Now Run Smooth Parallel Agents)](https://freedium-mirror.cfd/https://medium.com/@joe.njenga/i-tried-new-claude-code-git-worktree-i-now-run-smooth-parallel-agents-8e21627167b7?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处