git-worktrees

Claude Code 的 Git 工作树

概述

使用 Git 工作树，在不同分支上并行运行多个 Claude Code 会话。此技能提供简单的脚本和工作流，用于创建、管理和清理工作树，让你能够真正并行开发而不产生冲突。

为什么使用工作树？

• 并行开发：同时运行多个 Claude Code 实例
• 零冲突：每个工作树都有独立的文件状态
• 快速切换上下文：切换任务时无需暂存或提交
• 隔离实验：尝试不同方案，不影响主要工作
• 长时间运行的任务：让 Claude 在后台工作，同时继续在主目录中工作

---

快速开始

1. 创建新的工作树（超级简单！）

只需运行交互式脚本：

scripts/create_worktree.sh

脚本将会：

• ✅ 提示输入功能名称
• ✅ 创建新分支
• ✅ 设置工作树
• ✅ 在 VS Code / 编辑器中打开
• ✅ 提供 Claude Code 设置命令

就是这样！ 脚本会处理所有复杂操作。

---

2. 查看所有工作树

scripts/list_worktrees.sh

以清晰、格式化的列表显示所有工作树及其分支和状态。

---

3. 清理旧工作树

scripts/cleanup_worktrees.sh

交互式移除已合并或已废弃的工作树。

---

核心工作流

模式 1：并行开发功能

场景： 你希望 Claude 开发功能 A，同时自己开发功能 B。

步骤：

1. 为功能 A 创建工作树：

   scripts/create_worktree.sh
   # Enter: feature-a
   # Script creates: ../repo-feature-a/
   

2. 在新工作树中打开 Claude Code：

   • 脚本会输出路径
   • 打开 Claude Code 并导航到该目录
   • 运行 /init，帮助 Claude 熟悉项目

3. 给 Claude 分配任务：

   "Build the user authentication feature with OAuth support"
   

4. 继续在主目录中工作：

   • 原始目录保持不变
   • 没有冲突，无需等待
   • Claude 并行工作

5. 两边都完成后，进行合并：

   # Review Claude's work
   cd ../repo-feature-a
   git log
   
   # If good, merge back
   git checkout main
   git merge feature-a
   
   # Clean up
   scripts/cleanup_worktrees.sh
   

---

模式 2：长时间运行的重构

场景： 你希望 Claude 重构大型模块，同时继续开发。

步骤：

1. 创建重构工作树：

   scripts/create_worktree.sh
   # Enter: refactor-auth-module
   

2. 在重构工作树中启动 Claude：

   "Refactor the authentication module to use dependency injection"
   

3. 继续在主目录中进行日常工作：

   • 不受干扰
   • 没有合并冲突
   • 定期检查进度

4. 准备就绪后，审查并集成：

   cd ../repo-refactor-auth-module
   git log --oneline
   # Review changes
   
   # Merge when satisfied
   git checkout main
   git merge refactor-auth-module
   

---

模式 3：多个 AI Agent（高级）

场景： 你希望 3 个 Claude 实例同时开发不同功能。

步骤：

1. 创建 3 个工作树：

   scripts/create_worktree.sh  # feature-api-endpoints
   scripts/create_worktree.sh  # feature-ui-dashboard
   scripts/create_worktree.sh  # feature-email-notifications
   

2. 打开 3 个 Claude Code 会话：

   • 会话 1：../repo-feature-api-endpoints/
   • 会话 2：../repo-feature-ui-dashboard/
   • 会话 3：../repo-feature-email-notifications/

3. 为每个 Claude 分配任务：

   • Claude 1：“构建用户管理 REST API 端点”
   • Claude 2：“创建管理后台 UI”
   • Claude 3：“实现电子邮件通知系统”

4. 监控进度：

   scripts/list_worktrees.sh
   

5. 功能完成后逐一合并：

   # Feature by feature
   git checkout main
   git merge feature-api-endpoints
   git merge feature-ui-dashboard
   git merge feature-email-notifications
   
   # Clean up
   scripts/cleanup_worktrees.sh
   

---

模式 4：开发继续期间处理紧急修复

场景： Claude 正在开发某个功能时，生产环境出现了需要立即修复的错误。

步骤：

1. Claude 已在功能工作树中工作

   • 让它继续，不要打断

2. 从 main 创建紧急修复工作树：

   scripts/create_worktree.sh
   # Enter: hotfix-login-bug
   # Choose base branch: main
   

3. 自己修复错误，或使用另一个 Claude 会话：

   cd ../repo-hotfix-login-bug
   # Make fixes
   git add .
   git commit -m "Fix login redirect bug"
   

4. 将紧急修复合并到 main：

   git checkout main
   git merge hotfix-login-bug
   git push origin main
   

5. 将功能工作树与最新的 main 同步：

   cd ../repo-feature-xyz
   scripts/sync_worktree.sh
   # Merges latest main into feature branch
   

---

必备脚本

scripts/create_worktree.sh

以合适的默认设置交互式创建工作树。

功能：

1. 提示输入功能名称
2. 验证 Git 仓库
3. 从 main（或指定的基础分支）创建分支
4. 在并行目录中设置工作树
5. 输出设置说明

用法：

scripts/create_worktree.sh

# Prompts:
# Feature name: my-feature
# Base branch (default: main):
#
# Creates: ../repo-my-feature/
# Branch: my-feature

高级用法：

# Create from specific branch
scripts/create_worktree.sh --base develop

# Specify location
scripts/create_worktree.sh --dir ~/worktrees/my-feature

---

scripts/list_worktrees.sh

显示所有活动工作树及其状态。

输出：

╔════════════════════════════════════════════════╗
║            Active Git Worktrees                ║
╚════════════════════════════════════════════════╝

📁 Main Worktree
   Path: /home/user/project
   Branch: main
   Status: clean

📁 Feature Worktrees
   Path: /home/user/project-feature-api
   Branch: feature-api
   Status: 2 uncommitted changes

   Path: /home/user/project-refactor
   Branch: refactor-auth
   Status: clean

---

scripts/cleanup_worktrees.sh

交互式清理旧工作树。

功能：

• 列出所有工作树及其合并状态
• 识别已合并的分支（可安全移除）
• 提示确认
• 安全移除工作树和分支

用法：

scripts/cleanup_worktrees.sh

# Output:
# Found 3 worktrees
#
# 1. feature-api (merged to main) - Safe to remove
# 2. feature-dashboard (not merged) - Keep
# 3. old-experiment (not merged, 30 days old) - Consider removing
#
# Which worktrees to remove? (1,3): 1

---

scripts/sync_worktree.sh

使工作树与主分支保持同步。

功能：

1. 从远程获取最新内容
2. 将 main 合并到当前工作树分支
3. 提供指导以处理冲突

用法：

# From within a worktree
cd ../repo-feature-api
scripts/sync_worktree.sh

# Or specify worktree
scripts/sync_worktree.sh ../repo-feature-api

---

Claude Code 集成

重要提示：在每个工作树中运行 /init

在工作树中开启新的 Claude Code 会话时，务必先运行 /init：

/init

这可确保 Claude：

• 了解代码库结构
• 拥有适当的上下文
• 能正确浏览文件

推荐的 Claude Code 工作流

1. 创建工作树（使用脚本）
2. 在工作树目录中打开 Claude Code
3. 运行 /init，帮助 Claude 熟悉环境
4. 向 Claude 分配任务
5. 通过 git log 或文件监视来监控进度
6. 完成后检查
7. 满意后合并
8. 清理工作树

---

最佳实践

命名约定

好的名称：

• feature-user-auth ✅
• refactor-api-layer ✅
• hotfix-login-bug ✅
• experiment-new-db ✅

不好的名称：

• test ❌（过于含糊）
• wt1 ❌（毫无意义）
• fixes ❌（不明确）

推荐格式：

<type>-<short-description>

Types:
- feature-*
- refactor-*
- hotfix-*
- experiment-*
- review-*

---

目录结构

推荐布局：

~/projects/
  └── myapp/              # Main worktree (main branch)
      ├── myapp-feature-api/      # Feature worktree
      ├── myapp-refactor-auth/    # Refactor worktree
      └── myapp-hotfix-bug/       # Hotfix worktree

脚本默认将工作树创建为主目录的同级目录，并采用 <repo>-<branch-name> 命名模式。

---

何时使用工作树

✅ 适合使用工作树的场景：

• 并行运行多个 Claude Code 会话
• 同时处理互不相关的功能
• 进行耗时较长的重构
• 尝试重大更改
• 开发功能期间快速修复问题
• 在不中断工作的情况下进行代码审查

❌ 不适合使用工作树的场景：

• 简单切换分支（直接使用 git checkout）
• 小幅调整（改用 stash）
• 仅包含单个任务的工作流
• 生命周期很短的分支（少于 1 小时）

---

保持工作树同步

**问题：**功能分支可能会落后于 main。

**解决方案：**定期同步工作树：

# Option 1: Use the sync script
cd ../repo-feature-api
scripts/sync_worktree.sh

# Option 2: Manual sync
cd ../repo-feature-api
git fetch origin
git merge origin/main

建议频率：

• 长期开发的功能每天同步一次
• 合并重大更改到 main 后
• 创建 PR 前

---

管理多个工作树

快速查看所有工作树的状态：

scripts/list_worktrees.sh

定期清理（每周）：

scripts/cleanup_worktrees.sh

查找长期未使用的工作树：

# Worktrees with old commits
git worktree list | while read path branch commit; do
  cd "$path"
  last_commit=$(git log -1 --format=%cr)
  echo "$branch: Last commit $last_commit"
done

---

故障排除

问题：“fatal: invalid reference”

**原因：**分支名称包含无效字符

**解决方案：**仅使用字母数字字符和连字符：

# Bad
feature/my_feature  ❌

# Good
feature-my-feature  ✅

---

问题：“cannot remove worktree, path is not a working tree”

**原因：**工作树目录已被手动删除

**解决方案：**清理工作树引用：

git worktree prune

---

问题：Claude 在工作树中似乎“迷失”了

**原因：**打开工作树后未运行 /init

**解决方案：**在新工作树中启动 Claude 时，务必运行 /init：

/init

---

问题：同步工作树时出现合并冲突

**原因：**工作树中的更改与 main 冲突

**解决方案 1：**手动解决冲突：

cd ../repo-feature-api
git fetch origin
git merge origin/main
# Fix conflicts in editor
git add .
git commit -m "Merge main and resolve conflicts"

**解决方案 2：**如果要放弃工作树中的更改并重新开始：

cd ../repo-feature-api
git fetch origin
git reset --hard origin/main
# Start feature over

---

问题：出现“Cannot lock ref”错误

**原因：**多个工作树中存在同一分支

**解决方案：**不能在多个工作树中同时检出同一分支。请创建新分支：

scripts/create_worktree.sh
# Use a different branch name

---

问题：工作树占用过多磁盘空间

**原因：**Git 工作树共享 .git 目录，但文件会重复存储

**解决方案 1：**清理旧工作树：

scripts/cleanup_worktrees.sh

**解决方案 2：**对于大型代码库，使用 sparse-checkout：

git -C ../repo-feature-api sparse-checkout set src/ tests/

---

高级用法

自定义斜杠命令

为 Claude Code 创建 /worktree 命令。完整设置请参阅 references/slash_command_template.md。

设置后的用法：

/worktree feature-new-api

Claude 将：

1. 创建工作树
2. 提供设置说明
3. 提议在新的工作树中继续对话

---

在团队中共享工作树

工作树仅限本地使用，但你可以共享工作流：

1. 共享分支，而非工作树：

   cd ../repo-feature-api
   git push origin feature-api
   
   # Teammate creates their own worktree
   git worktree add ../repo-feature-api feature-api
   

2. 在团队文档中说明工作树结构

3. 在团队中使用一致的命名方式

---

工作树性能优化

对于大型仓库：

1. 使用 sparse-checkout（仅检出所需文件）：

   git -C ../repo-feature-api sparse-checkout init
   git -C ../repo-feature-api sparse-checkout set src/ tests/
   

2. 定期使用 worktree prune：

   git worktree prune
   

3. 将并发工作树数量限制为 3-5 个，以获得最佳性能

---

常见工作流汇总

快速参考

任务	命令
创建新工作树	scripts/create_worktree.sh
列出所有工作树	scripts/list_worktrees.sh
清理工作树	scripts/cleanup_worktrees.sh
与 main 同步	scripts/sync_worktree.sh
手动创建	git worktree add ../path branch-name
手动列出	git worktree list
手动移除	git worktree remove ../path
清理引用	git worktree prune

---

实际示例

示例 1：并行开发 API 和 UI

设置：

# Create API worktree
scripts/create_worktree.sh
# Name: feature-api

# Create UI worktree
scripts/create_worktree.sh
# Name: feature-ui

执行：

• Claude 1 在 ../repo-feature-api 中：“构建用于用户管理的 REST API”
• Claude 2 在 ../repo-feature-ui 中：“创建用于用户管理的 React UI”
• 你在 main 中：继续其他工作

合并：

git checkout main
git merge feature-api
git merge feature-ui
scripts/cleanup_worktrees.sh

---

示例 2：无需切换上下文即可进行代码审查

场景： Claude 正在开发功能，同时你需要审查 PR

设置：

# Claude is working in feature worktree
# You need to review PR #123

scripts/create_worktree.sh
# Name: review-pr-123
# Base: pr-branch-name

执行：

• 在 ../repo-review-pr-123 中审查代码
• Claude 继续在 ../repo-feature-xyz 中工作
• 无需切换上下文

清理：

# After review
scripts/cleanup_worktrees.sh
# Select review-pr-123

---

示例 3：无风险地进行实验

场景： 想尝试大幅重构，但不影响当前工作

设置：

scripts/create_worktree.sh
# Name: experiment-new-architecture

执行：

• 在 ../repo-experiment-new-architecture 中自由实验
• 主工作树保持稳定
• 如果实验失败，直接删除工作树即可

决策：

# If experiment succeeded
git checkout main
git merge experiment-new-architecture

# If experiment failed
scripts/cleanup_worktrees.sh
# Delete experiment worktree (no harm done)

---

提升效率的技巧

1. 为工作树起描述性名称

• 当你同时打开 5 个工作树时，就会庆幸自己这么做了

2. 始终运行 /init

• 在新工作树中打开 Claude 后，第一件事就是运行它

3. 频繁合并

• 不要让工作树数周都各自分叉
• 定期与 main 同步

4. 每周清理

• 每周五运行 scripts/cleanup_worktrees.sh
• 保持工作区整洁

5. 使用脚本

• 不要死记 git worktree 命令
• 脚本会处理边缘情况并进行验证

6. 监控进度

• 使用 scripts/list_worktrees.sh 查看当前活动项
• 定期检查工作树中的 git 日志

7. 限制并发会话

• 为获得最佳性能，最多使用 3-5 个工作树
• 数量再多就难以管理了

---

资源

脚本

• create_worktree.sh - 交互式创建工作树
• list_worktrees.sh - 显示所有活动工作树
• cleanup_worktrees.sh - 移除旧工作树
• sync_worktree.sh - 保持工作树同步

参考资料

• worktree_commands.md - Git worktree 命令完整参考
• best_practices.md - 详细的最佳实践和模式
• slash_command_template.md - 创建自定义 /worktree 命令

---

总结

Git worktrees 支持使用 Claude Code 真正实现并行开发：

✅ 运行多个 Claude 会话，互不冲突 ✅ 即时切换上下文，无需暂存更改 ✅ 安全地进行实验，不影响主工作区 ✅ 简单的脚本，处理所有复杂操作 ✅ 为常见场景提供简洁工作流

开始使用：

scripts/create_worktree.sh

就是这么简单！ 这些脚本让工作树易于使用且实用。