使用 Git Worktrees

概述

Git worktrees 创建共享同一仓库的隔离工作空间，允许在不切换分支的情况下同时处理多个分支。

核心原则：系统化的目录选择 + 安全验证 = 可靠的隔离。

开始时声明：“我正在使用使用-git-worktrees 技能来设置一个隔离的工作空间。”

目录选择流程

遵循此优先顺序：

1. 检查现有目录

# 按优先顺序检查
ls -d .worktrees 2>/dev/null     # 首选（隐藏目录）
ls -d worktrees 2>/dev/null      # 备选

如果找到：使用该目录。如果两者都存在，.worktrees 优先。

2. 检查 CLAUDE.md

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

如果指定了偏好：直接使用，无需询问。

3. 询问用户

如果没有找到目录，且 CLAUDE.md 中没有指定偏好：

未找到工作树目录。我应在哪里创建工作树？

1. .worktrees/（项目本地，隐藏）
2. ~/.config/superpowers/worktrees/<项目名>/（全局位置）

您偏好哪个？

安全验证

对于项目本地目录（.worktrees 或 worktrees）

在创建工作树之前，必须验证目录是否被忽略：

# 检查目录是否被忽略（遵守本地、全局和系统 gitignore）
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

根据杰西的规则“立即修复损坏”：

1. 向 .gitignore 添加相应的行
2. 提交更改
3. 继续创建工作树

为何关键：防止意外将工作树内容提交到仓库。

对于全局目录 (~/.config/superpowers/worktrees)

无需 .gitignore 验证——完全在项目外部。

创建步骤

1. 检测项目名称

project=$(basename "$(git rev-parse --show-toplevel)")

2. 创建工作树

# 确定完整路径
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# 使用新分支创建工作树
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. 运行项目设置

自动检测并运行适当的设置：

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

4. 验证干净的基线

运行测试以确保工作树以干净状态启动：

# 示例 - 使用项目适当的命令
npm test
cargo test
pytest
go test ./...

如果测试失败：报告失败，询问是继续还是调查。

如果测试通过：报告准备就绪。

5. 报告位置

工作树已准备就绪，位于 <完整路径>
测试通过（<N> 个测试，0 个失败）
准备实施 <功能名称>

快速参考

常见错误

跳过忽略验证

• 问题：工作树内容被跟踪，污染 git 状态
• 修复：在创建项目本地工作树之前，始终使用 git check-ignore

假设目录位置

• 问题：造成不一致，违反项目约定
• 修复：遵循优先级：现有 > CLAUDE.md > 询问

在测试失败的情况下继续

• 问题：无法区分新错误和预先存在的问题
• 修复：报告失败，获得明确许可后再继续

硬编码设置命令

• 问题：在使用了不同工具的项目上会失败
• 修复：从项目文件（package.json 等）自动检测

工作流程示例

你：我正在使用使用-git-worktrees 技能来设置一个隔离的工作空间。

[检查 .worktrees/ - 存在]
[验证被忽略 - git check-ignore 确认 .worktrees/ 被忽略]
[创建工作树：git worktree add .worktrees/auth -b feature/auth]
[运行 npm install]
[运行 npm test - 47 通过]

工作树已准备就绪，位于 /Users/用户名/myproject/.worktrees/auth
测试通过（47 个测试，0 个失败）
准备实施身份验证功能

危险信号

切勿：

• 未验证被忽略就创建工作树（项目本地）
• 跳过基线测试验证
• 在未询问的情况下，在测试失败时继续
• 当目录位置不明确时做出假设
• 跳过 CLAUDE.md 检查

始终：

• 遵循目录优先级：现有 > CLAUDE.md > 询问
• 验证项目本地目录是否被忽略
• 自动检测并运行项目设置
• 验证干净的测试基线

集成

被以下技能调用：

• brainstorming（阶段 4）- 当设计获得批准并要实施时必需
• subagent-driven-development – 在执行任何任务之前必需
• executing-plans – 在执行任何任务之前必需
• 任何需要隔离工作空间的技能

与以下技能搭配使用：

• finishing-a-development-branch – 工作完成后进行清理时必需