using-git-worktrees

使用 Git Worktrees

概述

Git worktrees 会创建彼此隔离、但共享同一仓库的工作区，因此可以同时在多个分支上工作，无需切换分支。

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

开始时声明：“我将使用 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 -- "$LOCATION/"

如果未被忽略：

优先选择已批准的外部 worktree 位置。如果必须存储在项目本地，请提出确切的忽略规则变更，并遵循仓库的提交策略；不要自动创建无关提交。

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

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

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

如果宿主提供了托管 worktree 的创建/归档 API，优先使用该 API。创建前，解析并记录明确指定的基准提交；当前 HEAD 和远程默认分支是不同的选择。验证分支/路径值，并保留现有的未提交更改。

创建步骤

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="$HOME/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

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

3. 运行项目设置

在设置前，检查与确切基准提交对应的 AGENTS.md、维护者文档、包/锁文件以及生命周期/构建脚本。以下是可选示例，并非需要全部执行的流程；请使用锁定的依赖项和项目授权的设置方式，不要自动执行未知代码：

# Node.js
if [ -f package-lock.json ]; then npm ci --ignore-scripts; 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 从干净状态开始：

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

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

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

5. 报告位置

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

快速参考

情况	操作
.worktrees/ 存在	使用它（验证已被忽略）
worktrees/ 存在	使用它（验证已被忽略）
两者都存在	使用 .worktrees/
两者都不存在	检查 CLAUDE.md → 询问用户
目录未被忽略	优先使用外部路径，或提出范围明确的忽略规则变更
基线测试失败	报告失败情况 + 询问
没有 package.json/Cargo.toml	跳过依赖安装

常见错误

跳过忽略状态验证

• **问题：**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 npm install]
[Run npm 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）——设计获批且即将开始实施时，必须使用
• 任何需要隔离工作区的技能

配合使用：

• finishing-a-development-branch——工作完成后，必须使用以进行清理
• executing-plans 或 subagent-driven-development——在此工作树中开展工作

使用时机

此技能适用于执行概述中描述的工作流或操作。

局限性

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并寻求澄清。