Overview
Git worktrees create isolated workspaces that share the same repository, allowing work on multiple branches simultaneously without switching.
Core principles: Systematic directory selection + safety verification = reliable isolation.
Announce at the start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
Directory selection process
Follow this priority order:
1. Check for existing directories
# 按优先顺序检查
ls -d .worktrees 2>/dev/null # 首选(隐藏目录)
ls -d worktrees 2>/dev/null # 备选
If found: Use that directory. If both exist,.worktrees takes precedence.
2. Check CLAUDE.md
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If a preference is specified: Use it directly without asking.
3. Ask the user
If there is no existing directory and no preference is set in CLAUDE.md:
未找到工作树目录。我应该在哪里创建工作树?
1. .worktrees/(项目本地,隐藏目录)
2. ~/.config/superpowers/worktrees/<project-name>/(全局位置)
你倾向哪个?
Safety verification
Project-local directories (.worktrees or worktrees)
Before creating a worktree, you must verify that the directory is ignored:
# 检查目录是否被忽略(遵循本地、全局和系统 gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
If it is not ignored:
Per Jesse's rule "fix broken things immediately":
- Add the corresponding entry to .gitignore
- Commit the change
- Continue creating the worktree
Why this is critical: Prevents accidentally committing worktree contents to the repository.
Global directory (~/.config/superpowers/worktrees)
No .gitignore verification needed—it is entirely outside the project.
Creation steps
1. Detect the project name
project=$(basename "$(git rev-parse --show-toplevel)")
2. Create the 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"
3. Run project setup
Automatically detect and run the corresponding setup command:
# 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. Verify the baseline is normal
Run tests to ensure the worktree's initial state is clean:
# 示例 - 使用项目对应的命令
npm test
cargo test
pytest
go test ./...
If tests fail: Report the failure and ask whether to continue or troubleshoot.
If tests pass: Report ready.
5. Report the location
工作树已就绪:<full-path>
测试通过(<N> 个测试,0 个失败)
准备实现 <feature-name>
Quick reference
| Situation | Action |
|---|---|
.worktrees/ exists |
Use it (verify it is ignored) |
worktrees/ exists |
Use it (verify it is ignored) |
| Both exist | Use .worktrees/ |
| Neither exists | Check CLAUDE.md → ask the user |
| Directory is not ignored | Add to .gitignore + commit |
| Baseline tests fail | Report failure + ask |
| No package.json/Cargo.toml | Skip dependency installation |
Common mistakes
Skipping ignore verification
- Problem: Worktree contents are tracked, polluting git status
- Fix: Always use this before creating a project-local worktree:
git check-ignore
Assuming the directory location
- Problem: Causes inconsistency and violates project conventions
- Fix: Follow the priority: existing directory > CLAUDE.md > ask
Continue with failing tests
- Problem: Cannot distinguish new bugs from existing issues
- Fix: Report the failure and continue only after explicit permission
Hardcoded setup commands
- Problem: Will fail on projects using different tools
- Fix: Auto-detect from project files (package.json, etc.)
Example workflow
你:我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。
[检查 .worktrees/ - 存在]
[验证已忽略 - git check-ignore 确认 .worktrees/ 已被忽略]
[创建工作树:git worktree add .worktrees/auth -b feature/auth]
[运行 npm install]
[运行 npm test - 47 个通过]
工作树已就绪:/Users/jesse/myproject/.worktrees/auth
测试通过(47 个测试,0 个失败)
准备实现 auth 功能
Red lines
Never:
- Create a project-local worktree without verifying it is ignored
- Skip baseline test verification
- Continue with failing tests without asking
- Assume directory location when ambiguous
- Skip CLAUDE.md check
Always:
- Follow directory priority: existing directory > CLAUDE.md > ask
- Verify project-local directories are ignored
- Auto-detect and run project setup
- Verify the test baseline is clean
Integration
Called by the following skills:
- brainstorming(Phase 4) - Required when the design is approved and implementation is needed
- subagent-driven-development - Required before executing any task
- executing-plans - Required before executing any task
- Any skill that needs an isolated workspace
Used with:
- finishing-a-development-branch - Required when cleaning up after work is complete