using-git-worktrees

使用 Git Worktrees

概述

Git worktree 可创建共享同一仓库的隔离工作区，让你无需切换分支即可同时处理多个分支。

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

开始时声明：“我正在使用 using-git-worktrees 技能来设置隔离工作区。”

目录选择流程

按以下优先级顺序操作：

1. 检查现有目录

# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

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

2. 检查 CLAUDE.md

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

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

3. 询问用户

如果两个目录都不存在，且 CLAUDE.md 中也没有偏好：

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

安全验证

对于项目内目录（.worktrees 或 worktrees）

创建 worktree 前，必须确认目录已被忽略：

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

按照 Jesse 的规则“立即修复损坏的问题”：

1. 在 .gitignore 中添加适当的条目
2. 提交此更改
3. 继续创建 worktree

**为何至关重要：**防止意外将 worktree 内容提交到仓库。

对于全局目录（~/.config/superpowers/worktrees）

无需验证 .gitignore，因为该目录完全位于项目之外。

创建步骤

1. 检测项目名称

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

2. 创建 Worktree

# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. 运行项目设置

自动检测并运行相应的设置流程：

# Ruby on Rails (primary)
if [ -f Gemfile ]; then bundle install; fi

# Rails + SQLite: populate development databases in the worktree.
# Delegates to the using-sqlite-worktrees skill. The helper reads database.yml
# from the MAIN working tree (where populated DBs live), so we cd back to main
# before invoking it. See failure contract below.
if [ -f Gemfile ] && [ -f config/database.yml ] && grep -q "adapter: sqlite3" config/database.yml; then
  WORKTREE_PATH="$(pwd)"
  MAIN_WORKTREE="$(git worktree list --porcelain | awk '/^worktree/ {print substr($0,10); exit}')"
  (cd "$MAIN_WORKTREE" && ruby "${CLAUDE_PLUGIN_ROOT}/skills/using-sqlite-worktrees/scripts/create_sqlite_worktree.rb" "$WORKTREE_PATH")
  SQLITE_EXIT=$?
  if [ $SQLITE_EXIT -ne 0 ]; then
    echo "SQLite worktree setup failed — skipping db:test:prepare and baseline tests."
    echo "Investigate the output above before continuing."
    exit $SQLITE_EXIT
  fi
fi

if [ -f Gemfile ] && [ -f config/database.yml ]; then bin/rails db:test:prepare; fi

# 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 初始状态干净：

# Ruby on Rails (primary)
bin/rails test

# Other project types
npm test      # Node.js
cargo test    # Rust
pytest        # Python
go test ./... # Go

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

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

5. 报告位置

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

快速参考

情况	操作
存在 .worktrees/	使用它（确认已被忽略）
存在 worktrees/	使用它（确认已被忽略）
两者都存在	使用 .worktrees/
两者都不存在	检查 CLAUDE.md → 询问用户
目录未被忽略	添加到 .gitignore 并提交
基线测试失败	报告失败情况并询问
没有 package.json/Cargo.toml	跳过依赖安装
Rails + SQLite 项目	在运行 db:test:prepare 前，委托给 using-sqlite-worktrees
using-sqlite-worktrees 失败	停止设置，跳过测试，并报告“数据库设置未完成”

常见错误

跳过忽略状态验证

• **问题：**Worktree 内容会被纳入跟踪，污染 git status
• **修复：**创建项目内 worktree 前，始终使用 git check-ignore

想当然地选择目录位置

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

测试失败仍继续

• **问题：**无法区分新 Bug 和已有问题
• **修复：**报告失败情况，获得明确许可后再继续

硬编码设置命令

• **问题：**遇到使用不同工具的项目时会失效
• **修复：**根据项目文件自动检测（如 package.json）

工作流示例

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run bundle install]
[Run bin/rails db:test:prepare]
[Run bin/rails test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

危险信号

绝不：

• 未确认 worktree 已被忽略就创建（项目内）
• 跳过基线测试验证
• 未经询问就继续处理测试失败的情况
• 在目录位置不明确时擅自决定
• 跳过 CLAUDE.md 检查

始终：

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

集成

由以下技能调用：

• brainstorming（阶段 4）——设计获批且即将开始实现时必须调用
• subagent-driven-development——执行任何任务前必须调用
• executing-plans——执行任何任务前必须调用
• 任何需要隔离工作区的技能

配合使用：

• finishing-a-development-branch——工作完成后必须用于清理
• using-sqlite-worktrees——检测到 Rails + SQLite 时必须委托，在 bundle install 后、db:test:prepare 前调用