SuperAPI AI 工具集

using-git-worktrees

编程与开发

查看项目

更新于 10-16 06:10

技能介绍

用途

该技能用于在开始需要与当前工作区隔离的功能开发,或在执行实现计划之前,创建隔离的 Git worktree。Git worktree 可创建共享同一仓库的隔离工作区,从而在不切换分支的情况下同时处理多个分支。其核心原则是:系统化的目录选择 + 安全校验 = 可靠的隔离。

使用开始时需声明:“I'm using the using-git-worktrees skill to set up an isolated workspace.”

目录选择流程

按以下优先级顺序执行:

  1. 检查已有目录:
ls -d .worktrees 2>/dev/null     # 首选(隐藏)
ls -d worktrees 2>/dev/null      # 备选

若找到则使用该目录;若两者都存在,.worktrees 优先。

  1. 检查 CLAUDE.md:
grep -i "worktree.*director" CLAUDE.md 2>/dev/null

若指定了偏好,直接使用,不再询问。

  1. 询问用户:若目录不存在且 CLAUDE.md 无偏好,则询问用户选择 .worktrees/(项目内、隐藏)或 ~/.config/superpowers/worktrees/<project-name>/(全局位置)。

安全校验

对于项目内目录(.worktrees 或 worktrees),创建 worktree 前必须校验 .gitignore:

grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

若不在 .gitignore 中,则按“立即修复损坏之处”的规则,向 .gitignore 添加相应行、提交该更改,然后继续创建 worktree。这一步至关重要,可防止意外将 worktree 内容提交到仓库。

对于全局目录(~/.config/superpowers/worktrees),无需校验 .gitignore,因为它在项目之外。

创建步骤

  1. 检测项目名称:
project=$(basename "$(git rev-parse --show-toplevel)")
  1. 创建 worktree:
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"
  1. 运行项目初始化(自动检测):
# 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
  1. 校验干净基线:运行测试以确保 worktree 起始状态干净,例如 npm test、cargo test、pytest、go test ./...。若测试失败,报告失败并询问是继续还是排查;若通过,报告就绪。

  2. 报告位置:

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

快速参考

  • .worktrees/ 存在:使用它(校验 .gitignore)
  • worktrees/ 存在:使用它(校验 .gitignore)
  • 两者都存在:使用 .worktrees/
  • 两者都不存在:检查 CLAUDE.md → 询问用户
  • 目录不在 .gitignore 中:立即添加并提交
  • 基线测试失败:报告失败并询问
  • 无 package.json/Cargo.toml:跳过依赖安装

常见错误

  • 跳过 .gitignore 校验:会导致 worktree 内容被跟踪、污染 git status;修复方法是创建项目内 worktree 前始终 grep .gitignore。
  • 假设目录位置:会造成不一致、违反项目约定;修复方法是遵循优先级:已有 > CLAUDE.md > 询问。
  • 在测试失败时继续:无法区分新缺陷与既有问题;修复方法是报告失败并获取明确许可后再继续。
  • 硬编码初始化命令:在采用不同工具的项目上会失效;修复方法是根据项目文件(package.json 等)自动检测。

示例工作流

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

[检查 .worktrees/ - 存在] [校验 .gitignore - 包含 .worktrees/] [创建 worktree: git worktree add .worktrees/auth -b feature/auth] [运行 npm install] [运行 npm test - 47 passing]

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

红线

绝不:在未校验 .gitignore 的情况下创建项目内 worktree;跳过基线测试校验;在测试失败且未询问的情况下继续;在目录位置不明确时假设位置;跳过 CLAUDE.md 检查。

始终:遵循目录优先级(已有 > CLAUDE.md > 询问);对项目内目录校验 .gitignore;自动检测并运行项目初始化;校验干净的测试基线。

集成

被以下调用:brainstorming(第 4 阶段)——当设计获批且随后进行实现时为必需;任何需要隔离工作区的技能。

搭配使用:finishing-a-development-branch——工作完成后清理时为必需;executing-plans 或 subagent-driven-development——工作在该 worktree 中进行。