Superpowers 教程 6：using-git-worktrees（Git Worktree 并行开发）

教程概述

系列目录：Superpowers 教程系列索引

using-git-worktrees 是 Superpowers 的环境隔离技能。它帮助你在开始新功能时创建独立的工作目录，实现并行开发而不互相干扰。

你将学到

✅ Git Worktrees 的核心概念
✅ 为什么需要隔离开发环境
✅ Worktree 的完整工作流
✅ 与分支策略的配合
✅ 实际应用场景

为什么需要 Git Worktrees？

传统分支开发的问题

flowchart LR
    A[主分支开发中] --> B[紧急 Bug 修复]
    B --> C[暂存当前修改]
    C --> D[切换分支]
    D --> E[修复 Bug]
    E --> F[切回原分支]
    F --> G[恢复工作]
    G --> H[上下文丢失]
    
    style C fill:#ffcccc
    style H fill:#ffcccc

Worktree 的解决方案

flowchart TD
    A[主工作区] --> B[开始新功能]
    B --> C[创建新 Worktree]
    C --> D[独立目录]
    D --> E[并行开发]
    E --> F[互不干扰]
    
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e8f5e9

效果对比

场景	传统方式	Worktree 方式
上下文切换	需要 stash	直接切换目录
并行功能	容易冲突	完全隔离
编译/依赖	可能冲突	互相独立
心理压力	怕破坏当前工作	安全隔离

Git Worktrees 核心概念

什么是 Worktree？

Git Worktree 允许你从同一个仓库创建多个独立的工作目录，每个目录可以：

检出不同的分支
有独立的暂存区
独立运行构建/测试
共享 Git 对象（节省空间）

仓库结构

repository.git/          # 主仓库（bare repository）
├── objects/            # 所有对象存储（共享）
├── refs/               # 所有引用（共享）
└── ...

worktree-main/          # 主工作区
├── .git/              # 指向 repository.git
├── src/
└── ...

worktree-feature-a/    # 功能 A 工作区
├── .git/              # 指向 repository.git
├── src/               # 不同的分支
└── ...

worktree-feature-b/    # 功能 B 工作区
├── .git/              # 指向 repository.git
├── src/               # 另一个分支
└── ...

Worktree vs 分支

分支 (Branch)          Worktree
--------              --------
逻辑隔离              物理隔离
同一目录              不同目录
需要切换              并行存在
共享暂存区            独立暂存区

Superpowers Worktree 技能详解

触发时机

using-git-worktrees 在以下场景自动触发：

开始新功能 - 设计文档批准后
执行实现计划 - 准备开始实现前
并行开发 - 需要同时开发多个功能时

自动执行流程

sequenceDiagram
    participant U as 用户
    participant AI as AI 助手
    participant G as Git
    participant V as 验证

    U->>AI: 开始实现标签功能
    AI->>AI: 触发 using-git-worktrees
    AI->>G: 检查当前状态
    G-->>AI: 当前在 main 分支
    AI->>G: 创建 worktree: feature-tag-system
    G-->>AI: worktree 创建成功
    AI->>V: 运行项目测试
    V-->>AI: 测试通过
    AI->>U: worktree 已就绪，可以开始开发
    
    Note over AI,U: 工作目录：../theme-stack-blog-feature-tag-system

智能目录命名

Superpowers 会自动生成有意义的目录名：

原仓库：theme-stack-blog
新功能：标签系统

生成的 worktree:
theme-stack-blog-feature-tag-system/
theme-stack-blog-fix-login-bug/
theme-stack-blog-refactor-api/

完整工作流程

步骤 1: 创建 Worktree

# Superpowers 自动执行
# 语法：git worktree add <path> -b <branch>

git worktree add ../theme-stack-blog-feature-tag -b feature/tag-system

输出：

Preparing worktree (new branch 'feature/tag-system')
HEAD is now at abc123 Add new documentation

步骤 2: 验证环境

# 进入新 worktree
cd ../theme-stack-blog-feature-tag

# 确认分支
git branch
# * feature/tag-system
#   main

# 确认目录结构
ls -la
# .git
# src/
# tests/
# ...

# 运行基准测试
npm test  # 或 pytest, etc.
# ✅ 所有测试通过

步骤 3: 开始开发

# 在新 worktree 中开发
# 完全独立于主工作区

# 修改代码
vim src/components/TagList.js

# 提交
git add .
git commit -m "feat: 实现标签列表组件"

# 主工作区不受影响，可以继续其他工作

步骤 4: 完成功能

# 所有功能完成并测试通过
# 准备合并

# 选项 1: 合并到 main
git checkout main
git merge feature/tag-system

# 选项 2: 创建 Pull Request
git push origin feature/tag-system
# 在 GitHub 创建 PR

# 选项 3: 保留 worktree 继续测试
# 暂时不合并

步骤 5: 清理 Worktree

# 功能已合并，清理 worktree

# 返回主仓库
cd ../theme-stack-blog

# 删除 worktree
git worktree remove ../theme-stack-blog-feature-tag

# 删除分支（如果已合并）
git branch -d feature/tag-system

常用 Worktree 命令

查看 Worktrees

# 列出所有 worktrees
git worktree list

# 输出示例：
# /home/user/theme-stack-blog         abc1234 [main]
# /home/user/theme-stack-blog-feature def5678 [feature/tag]

创建 Worktree

# 创建新分支的 worktree
git worktree add <path> -b <new-branch>

# 检出已有分支的 worktree
git worktree add <path> <existing-branch>

# 示例
git worktree add ../myproj-feature -b feature/new-feature
git worktree add ../myproj-fix fix/existing-branch

删除 Worktree

# 删除 worktree（分支保留）
git worktree remove <path>

# 强制删除（即使有未提交修改）
git worktree remove <path> --force

# 示例
git worktree remove ../myproj-feature

清理无效引用

# 清理已删除的 worktrees
git worktree prune

# 查看详细信息
git worktree list --verbose

实际应用场景

场景 1: 并行开发多个功能

主工作区：维护/修复小 bug
├── worktree-feature-a: 功能 A 开发
├── worktree-feature-b: 功能 B 开发
└── worktree-experiment: 技术验证

操作：

# 主工作区
cd ~/projects/myapp
git checkout main

# 功能 A
cd ~/projects/myapp-feature-a
git checkout feature/a
# 开发功能 A

# 功能 B
cd ~/projects/myapp-feature-b
git checkout feature/b
# 开发功能 B

# 需要切换？直接 cd 就行，不用 stash！

场景 2: 代码审查修复

# PR 需要修改
cd ~/projects/myapp-pr-fix

# 检出 PR 分支
git checkout pr/123-fix

# 进行修改
# 主工作区不受影响

# 完成后推送
git push origin pr/123-fix

场景 3: 多版本维护

# 同时维护多个版本
git worktree add ../myapp-v1 v1.x
git worktree add ../myapp-v2 v2.x
git worktree add ../myapp-main main

# 可以同时：
# - 在 v1.x 修复 bug
# - 在 v2.x 添加功能
# - 在 main 开发新功能

场景 4: 依赖/构建隔离

# 不同功能需要不同的依赖版本
# worktree 可以有独立的 node_modules

worktree-feature-a/
└── node_modules/  # React 17

worktree-feature-b/
└── node_modules/  # React 18

Superpowers Worktree 配置

配置文件

git_worktrees:
  # 启用自动 worktree 创建
  enabled: true
  
  # 目录命名模式
  naming:
    pattern: "{repo}-{type}-{name}"
    # {repo} - 仓库名
    # {type} - feature/bugfix/hotfix
    # {name} - 功能名称（slugified）
  
  # 自动验证
  verify:
    run_tests: true
    test_command: "npm test"  # 或 "pytest", "make test"
    timeout_seconds: 300
  
  # 清理策略
  cleanup:
    auto_remove_merged: true
    remind_stale_days: 7

目录选择

git_worktrees:
  # 工作区存放位置
  location:
    # 选项 1: 仓库同级目录（默认）
    strategy: sibling
    # 生成：../repo-name-feature
    
    # 选项 2: 集中目录
    # strategy: centralized
    # base_path: ~/worktrees/
    # 生成：~/worktrees/repo-name-feature/

最佳实践

1. 命名规范

# ✅ 好：清晰描述用途
git worktree add ../app-feature-auth -b feature/auth
git worktree add ../app-fix-login-bug -b fix/login-bug

# ❌ 坏：不清晰的命名
git worktree add ../temp -b test1
git worktree add ../work -b abc

2. 及时清理

# 定期检查并清理
git worktree list

# 删除已合并的 worktrees
git worktree remove ../app-feature-auth

# 清理孤儿 worktrees
git worktree prune

3. 独立构建

# 每个 worktree 独立构建
cd worktree-feature-a
npm install  # 独立的 node_modules
npm run build

# 不会影响其他 worktree

4. 避免共享状态

# ❌ 不要在 worktrees 之间共享状态
# 每个 worktree 应该是独立的

# ✅ 正确的做法
# - 独立的 node_modules
# - 独立的 .env 文件
# - 独立的构建产物

常见问题

Q1: Worktree 和 Stash 有什么区别？

答：

	Stash	Worktree
本质	暂存修改	独立工作区
使用场景	临时切换	长期并行开发
存储位置	.git/refs/stash	独立目录
切换成本	低（但要记住恢复）	低（直接 cd）

Q2: Worktree 会占用很多空间吗？

答：不会太多，因为：

Git 对象是共享的
只有工作目录文件是独立的
可以使用 symlink 共享 node_modules

Q3: Worktree 的分支可以 push 吗？

答：可以，完全正常：

cd worktree-feature
git push origin feature/my-feature

Q4: 如何处理冲突？

答：和普通分支一样：

# 在 worktree 中
git pull origin main
# 如果有冲突，正常解决
git merge --abort  # 如果需要放弃

Worktree 与 Superpowers 其他技能

with brainstorming

brainstorming 完成
    ↓
using-git-worktrees 创建隔离环境
    ↓
开始实现

with writing-plans

计划完成
    ↓
using-git-worktrees 创建环境
    ↓
subagent-driven-development 执行

with TDD

worktree 创建并验证
    ↓
test-driven-development 开始
    ↓
在隔离环境中写测试

小结

using-git-worktrees 提供物理隔离的开发环境：

并行开发 - 多个功能同时进行
上下文保护 - 不需要 stash 切换
安全隔离 - 实验不影响主工作
依赖独立 - 不同版本互不干扰

关键要点

✅ 每个功能独立 worktree
✅ 及时清理已完成的 worktree
✅ 独立构建和测试
✅ 清晰的命名规范

命令速查

# 创建
git worktree add <path> -b <branch>

# 查看
git worktree list

# 删除
git worktree remove <path>

# 清理
git worktree prune

系列导航：

← 上一篇：教程 5：systematic-debugging - 系统化调试方法
→ 下一篇：教程 7：代码审查技能完全指南
返回：教程系列索引