使用 Git Worktrees (using-git-worktrees)

使用 Git Worktrees（using-git-worktrees）

概述

using-git-worktrees 是用于创建隔离工作环境的 Skill。

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 偏好：

未找到 worktree 目录。我应该在哪里创建 worktrees？

1. .worktrees/ (项目本地，隐藏)
2. ~/.config/superpowers/worktrees/<project-name>/ (全局位置)

你偏好哪个？

安全验证

对于项目本地目录

创建 worktree 前必须验证目录被忽略：

# 检查目录是否被忽略
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

按 Jesse 的规则”立即修复坏掉的东西”：

添加适当行到 .gitignore
提交更改
继续创建 worktree

为什么关键：防止意外将 worktree 内容提交到仓库。

对于全局目录

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

创建步骤

1. 检测项目名称

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

2. 创建 Worktree

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

# 用新分支创建 worktree
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. 验证干净的基线

运行测试确保 worktree 从干净的基线开始：

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

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

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

5. 报告位置

Worktree 已就绪于 <完整路径>
测试通过 (<N> 个测试，0 失败)
准备实现 <功能名>

常见错误

错误	问题	修复
跳过 ignore 验证	Worktree 内容被跟踪，污染 git status	创建项目本地 worktree 前始终用 git check-ignore
假设目录位置	创建不一致，违反项目约定	遵循优先级：现有 > CLAUDE.md > 问
测试失败继续	无法区分新 bug 和已有问题	报告失败，获得明确许可继续
硬编码设置命令	在使用不同工具的项目上失败	从项目文件自动检测

速查卡片

何时使用

开始需要隔离的功能工作
执行实现计划前
需要同时在多个分支上工作

关键要点

先检查现有目录
验证 .gitignore
运行基线测试
报告位置

目录优先级

.worktrees/ (首选)
worktrees/
CLAUDE.md 指定
询问用户

禁止

不验证 .gitignore 就创建
不运行基线测试
测试失败不询问就继续

关联 Skill

前置：brainstorming（确定功能范围）和 writing-plans（制定实现计划）。
后续：executing-plans 或 subagent-driven-development（在实际隔离环境中执行）。
互补：finishing-a-development-branch（分支完成后的处理）。

查看源文件: GitHub原始文件