using-git-worktrees

using-git-worktrees Skill 多维度简评

综合评分:8.6 / 10 ⭐⭐⭐⭐⭐ 类别:Git / 工作流 / 并行开发 仓库:obra/superpowers 维护者:Jesse Vincent / Prime Radiant 引用:Superpowers README · CSDN 详解 · 掘金原理

一、核心定位与价值

Git worktree 是**“用多个工作区并行开发”**的官方解决方案。using-git-worktrees Skill 强制”开始新功能前先开 worktree”,避免主分支被污染 + 支持并行任务 + 易于回滚。

核心原则:“开始需要与当前工作区隔离的功能工作,或执行实施计划前” 目录选择优先级:.worktrees/ → 项目内其他目录 → 询问人类 安全:验证 .worktrees/ 在 .gitignore 中,避免 worktree 内容被 commit

适用场景

• 开始新功能开发
• 多分支并行开发
• 实验性改动(不确定要不要保留)
• 实施一个完整 plan
• 不污染主工作区

不适用场景

• 1 行修改
• 已经有一个 worktree
• 主工作区是干净的,直接用 main

二、核心机制

2.1 什么是 Git Worktree

Git worktree 允许同一个 git 仓库有多个工作目录:

• 主 worktree:~/projects/myapp(main 分支)
• 副 worktree:~/projects/myapp/.worktrees/feature-a(feature-a 分支)
• 副 worktree:~/projects/myapp/.worktrees/feature-b(feature-b 分支)

共享同一份 .git 目录,但工作区独立。

2.2 优势

2.3 跟 git checkout 对比

三、完整工作流

3.1 目录选择优先级

# 优先级 1: .worktrees/ (Skill 首选)
.worktrees/feature-xyzzy -b feature-xyzzy

# 优先级 2: 项目本地其他目录
.worktrees/ 或 .branches/ 等

# 优先级 3: 查看 CLAUDE.md
cat CLAUDE.md | grep -A5 "worktree"

# 优先级 4: 询问用户
"项目没有标准 worktree 目录,放哪?"

3.2 创建 Worktree

# 1. 验证 .worktrees/ 在 .gitignore 中
git check-ignore .worktrees/ || echo "WARNING: .worktrees/ not in .gitignore"

# 2. 创建 worktree + 新分支
git worktree add .worktrees/feature-xyzzy -b feature-xyzzy

# 3. 跑 baseline 测试(确保干净)
cd .worktrees/feature-xyzzy
npm install  # 或 pnpm install
npm test     # 期望:全部通过

3.3 在 Worktree 中工作

# 4. 编辑代码、提交
git add .
git commit -m "feat: implement feature xyzzy"

# 5. 跑测试
npm test

# 6. 完成后(交给 finishing-a-development-branch)
# - merge / PR / keep / discard

3.4 完整脚本

#!/bin/bash
# 简化版 Skill 行为
set -e

BRANCH=$1
if [ -z "$BRANCH" ]; then
  echo "Usage: ./new-worktree.sh <branch-name>"
  exit 1
fi

# 1. 验证 .worktrees 忽略
if ! git check-ignore .worktrees/ 2>/dev/null; then
  echo "ERROR: .worktrees/ not in .gitignore"
  exit 1
fi

# 2. 创建
git worktree add ".worktrees/$BRANCH" -b "$BRANCH"

# 3. 跑 baseline
cd ".worktrees/$BRANCH"
if [ -f "package.json" ]; then
  npm install
  npm test
elif [ -f "go.mod" ]; then
  go mod download
  go test ./...
elif [ -f "requirements.txt" ]; then
  pip install -r requirements.txt
  pytest
fi

echo "Worktree ready at .worktrees/$BRANCH"

四、并行开发实战

4.1 多个 worktree + 多个 Claude

# Terminal 1
cd .worktrees/feature-auth
claude  # 一个 Claude 会话

# Terminal 2
cd .worktrees/feature-payment
claude  # 另一个 Claude 会话

# Terminal 3
cd .worktrees/bugfix-1234
claude  # 第三个 Claude 会话

4.2 典型场景

来源:Claude Code 团队实践

# 场景:同时处理 3 件事
git worktree add .worktrees/feature-xyz -b feature-xyz
git worktree add .worktrees/fix-1234 -b fix-1234
git worktree add .worktrees/upgrade-react -b upgrade-react

# 3 个 Claude 实例同时跑
# - 终端 1: 开发 feature-xyz
# - 终端 2: 修复 bug 1234
# - 终端 3: 升级 React 19

4.3 Claude Code 团队最爱

“Worktree 模式是 Claude Code 团队提高生产力的最大来源。” —— 来源:Anthropic 内部

具体实践:

• 3-5 个 worktree 并行(人手一个 Claude)
• 命名约定:feature-xxx、fix-xxx、analysis
• 配合 tmux + shell alias(za / zb / zc)
• 一个 “analysis” worktree 只做”读日志 / 跑 BigQuery”不污染主开发

五、与 Superpowers 其他 Skills 配合

完整工作流:

[1] brainstorming
  ↓
[2] writing-plans (写到 docs/plans/...)
  ↓
[3] using-git-worktrees (创建 worktree)
  ↓
[4] subagent-driven-development (派 subagent 实施)
  ↓
[5] test-driven-development (每个 task)
  ↓
[6] verification-before-completion (跑测试)
  ↓
[7] finishing-a-development-branch (merge / PR / 清理)

六、5 大实战技巧

6.1 命名规范

# ✅ GOOD
.worktrees/feature-user-auth
.worktrees/fix-login-redirect
.worktrees/upgrade-react-19
.worktrees/analysis-bigquery

# ❌ BAD
.worktrees/test1
.worktrees/asdf
.worktrees/branch-1

6.2 配合 tmux + alias

# ~/.zshrc
alias za='cd ~/projects/myapp/.worktrees/feature-a && claude'
alias zb='cd ~/projects/myapp/.worktrees/feature-b && claude'
alias zc='cd ~/projects/myapp/.worktrees/feature-c && claude'

6.3 配合并行任务

# 同时跑 5 个 worktree
for branch in auth payment fix-1234 upgrade perf-test; do
  git worktree add ".worktrees/$branch" -b "$branch"
done

6.4 清理已完成 worktree

# Skill 自动清理(finishing-a-development-branch)
# 手动清理
git worktree remove .worktrees/feature-xyz
git branch -d feature-xyz  # 删除已合并分支

6.5 baseline 测试

# 创建 worktree 后,跑 baseline 确保干净
cd .worktrees/feature-xyz
npm install
npm test
# 期望:全部通过
# 如果失败,可能主分支有 broken test,先修主分支

七、6 大反模式

7.1 worktree 目录没加 .gitignore

# ❌ BAD - worktree 内容被意外 commit
git add .worktrees/  # 灾难

# ✅ GOOD
# .gitignore
.worktrees/
.worktrees/*
!.worktrees/.gitkeep

7.2 同一分支开多个 worktree

# ❌ 错误
git worktree add .worktrees/feature-a -b feature-a
git worktree add .worktrees/feature-a-dup -b feature-a
# Git 报错:branch already checked out

7.3 在主 worktree 改 worktree 子模块

# ❌ BAD
cd main_project
vim .worktrees/feature-a/some_file.go  # 不会被 worktree 看到

# ✅ GOOD
cd .worktrees/feature-a
vim some_file.go

7.4 不跑 baseline 就开干

# ❌ 跳到 worktree 直接改代码
git worktree add .worktrees/feature
# 改代码
# commit
# → 主分支可能已经 broken

7.5 长期 worktree 不清理

# ❌ 6 个月后 10 个 worktree 残留
$ git worktree list
.worktrees/feature-a  dead
.worktrees/feature-b  dead
...

7.6 在 worktree 里 git 操作主分支

# ❌ BAD - 容易冲突
cd .worktrees/feature
git checkout main  # 工作区混乱

# ✅ 切回主 worktree
cd ~/projects/myapp
git checkout main

八、Q&A

Q: 跟 git stash 区别? A: stash 是”暂存当前修改”;worktree 是”完全独立的工作区”。

Q: worktree 共享 .git 吗? A: 共享 .git 目录,各自独立的工作区文件。

Q: 性能影响? A: 几乎没有。branch 切换是 O(1)。

Q: 适合 Windows 吗? A: Git 2.5+ 支持,Windows OK。

Q: IDE 支持? A: VS Code / JetBrains 都能打开多个 worktree。

Q: 跟 “git worktree prune” 关系? A: git worktree prune 清理无效的 worktree 引用。

Q: 必须用 Claude Code 吗? A: 不必须。worktree 本身是 Git 特性,任何场景都适用。

Q: 学习曲线? A: 30 分钟上手,1 天习惯。

九、Prompt 模板

模板 1:创建 worktree

请用 using-git-worktrees 流程:
1. 验证 .worktrees/ 在 .gitignore
2. 创建 .worktrees/feature-user-auth
3. 跑 baseline 测试
4. 准备开始 writing-plans

模板 2:并行 3 个任务

请用 using-git-worktrees + dispatching-parallel-agents:
1. 创建 3 个 worktrees:
   - .worktrees/fix-bug-1234
   - .worktrees/refactor-payment
   - .worktrees/upgrade-deps
2. 在每个里跑 baseline
3. 派 3 个 subagent 并行处理

模板 3:清理

请用 finishing-a-development-branch:
1. 跑全量测试
2. 列出 .worktrees/* 状态
3. 提供选项:merge / PR / keep / discard
4. 清理已选 worktree

十、真实踩坑案例

案例 1:worktree 内容被 commit

现象:git add . 把整个 worktree 文件夹加进去。 根因:.worktrees/ 没在 .gitignore。 解决:立刻 revert + 加 .gitignore。

案例 2:baseline 测试失败

现象:worktree 创建后 npm test 失败。 根因:主分支本来就 broken。 解决:先修主分支,再开 worktree。

案例 3:worktree 占满磁盘

现象:5 个 worktree 各装 200MB node_modules = 1GB。 解决:用 pnpm 共享 store / npm ci --prefer-offline。

案例 4:worktree 残留

现象:3 个月后 8 个 worktree 没人清理。 解决:在 CLAUDE.md 加”每月清理”hook。

案例 5:worktree 跨设备

现象:Mac worktree 拉到 Windows 出问题。 根因:node_modules 平台特定。 解决:rm -rf node_modules && npm install。

案例 6:worktree 中 git pull 失败

现象:git pull 报”ref locked”。 根因:另一个 worktree 在 push。 解决:git worktree list 查所有 worktree 状态。

案例 7:worktree 合并冲突

现象:3 个 worktree 都改同一个文件。 解决:worktree 间串行合并 + rebase。

案例 8:worktree 命名冲突

现象:worktree 目录名跟分支名不一致。 解决:命名规范统一(worktree/branch-name)。

案例 9:IDE 找不到文件

现象:VS Code 打开 worktree 目录但文件不显示。 解决:code . 在 worktree 根目录重新打开。

案例 10:worktree 中 git hooks 不工作

现象:worktree 里 commit 触发不了 hook。 根因:worktree 共享 hooks 但 core.hooksPath 可能不同。 解决:git config core.hooksPath .git/hooks 在 worktree 里设。

十一、真实战绩

来源:Claude Code 团队实践

十二、与其他工具对比

十三、安装

# Claude Code
/plugin marketplace add obra/superpowers
/plugin install superpowers@claude-plugins-official

# 通用
npx skills add obra/superpowers --skill using-git-worktrees

# Git worktree 本身是 Git 2.5+ 自带
git --version  # >= 2.5

# 验证
git worktree add --help

十四、总结

核心价值:

• 强制隔离工作区
• 支持并行 Claude 会话
• 避免主分支污染
• 易于回滚
• 与 finishing-a-development-branch 配合清理

适用人群:

• 多任务并行开发者
• AI 编程重度用户
• 团队 Lead
• 长期项目维护者

投入产出比:⭐⭐⭐⭐⭐(5/5)—— AI 编程必装。

何时不要用:

• 1 行修改
• 已经在 worktree 里
• 一次性脚本
• 完全干净的主分支(直接用 main)

参考链接:

• Superpowers 官方仓库
• CSDN: Superpowers Skills 完整探索
• 掘金: Superpowers 原理解析
• chongwenz: Superpowers 常用命令
• Git Worktree 官方文档
• 配套:finishing-a-development-branch | writing-plans | subagent-driven-development