using-git-worktrees
Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- using-git-worktrees
- risk
- critical
- tags
- [ "git", "using", "worktrees" ]
- author
- Mr-Nobody-Anonymous
- source
- community
- version
- 1.0.0
- date_added
- 2026-02-27
- description
- Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
- compatibility
- { "codex": "*", "cursor": ">=0.40", "skillhub": "*", "claude-code": ">=1.0" }
- network_access
- false
- credential_access
- false
- filesystem_access
- write
- destructive_operations
- false
- disable-model-invocation
- false
03 SKILL.md 正文
Using Git Worktrees
Overview
Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
Core principle: Systematic directory selection + safety verification = reliable isolation.
Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
Directory Selection Process
Follow this priority order:
1. Check Existing Directories
# Check in priority order
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
If found: Use that directory. If both exist, .worktrees wins.
2. Check CLAUDE.md
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If preference specified: Use it without asking.
3. Ask User
If no directory exists and no CLAUDE.md preference:
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?
Safety Verification
For Project-Local Directories (.worktrees or worktrees)
MUST verify directory is ignored before creating 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
If NOT ignored:
Per Jesse's rule "Fix broken things immediately":
- Add appropriate line to .gitignore
- Commit the change
- Proceed with worktree creation
Why critical: Prevents accidentally committing worktree contents to repository.
For Global Directory (~/.config/superpowers/worktrees)
No .gitignore verification needed - outside project entirely.
Creation Steps
1. Detect Project Name
project=$(basename "$(git rev-parse --show-toplevel)")
2. Create 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. Run Project Setup
Auto-detect and run appropriate setup:
# 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 Clean Baseline
Run tests to ensure worktree starts clean:
# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
If tests fail: Report failures, ask whether to proceed or investigate.
If tests pass: Report ready.
5. Report Location
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
Quick Reference
| Situation | Action |
|---|---|
.worktrees/ exists |
Use it (verify ignored) |
worktrees/ exists |
Use it (verify ignored) |
| Both exist | Use .worktrees/ |
| Neither exists | Check CLAUDE.md → Ask user |
| Directory not ignored | Add to .gitignore + commit |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
Common Mistakes
Skipping ignore verification
- Problem: Worktree contents get tracked, pollute git status
- Fix: Always use
git check-ignorebefore creating project-local worktree
Assuming directory location
- Problem: Creates inconsistency, violates project conventions
- Fix: Follow priority: existing > CLAUDE.md > ask
Proceeding with failing tests
- Problem: Can't distinguish new bugs from pre-existing issues
- Fix: Report failures, get explicit permission to proceed
Hardcoding setup commands
- Problem: Breaks on projects using different tools
- Fix: Auto-detect from project files (package.json, etc.)
Example Workflow
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
Red Flags
Never:
- Create worktree without verifying it's ignored (project-local)
- Skip baseline test verification
- Proceed with failing tests without asking
- Assume directory location when ambiguous
- Skip CLAUDE.md check
Always:
- Follow directory priority: existing > CLAUDE.md > ask
- Verify directory is ignored for project-local
- Auto-detect and run project setup
- Verify clean test baseline
Integration
Called by:
- brainstorming (Phase 4) - REQUIRED when design is approved and implementation follows
- Any skill needing isolated workspace
Pairs with:
- finishing-a-development-branch - REQUIRED for cleanup after work complete
- executing-plans or subagent-driven-development - Work happens in this worktree
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
When NOT to Use
- Do not use for unrelated tasks or domains outside the stated scope.
- Do not use for minor trivial edits where standard direct execution suffices.
- Do not use to bypass required human confirmation or security approvals.
04 同仓库更多 Skills
dei-assessment
Assess diversity, equity, and inclusion with metrics. TRIGGERS - Use when user needs help with dei-assessment related tasks.
dei-action-plan
Create DEI action plans with goals and initiatives. TRIGGERS - Use when user needs help with dei-action-plan related tasks.
culture-fit-assessment
Design culture add assessment processes. TRIGGERS - Use when user needs help with culture-fit-assessment related tasks.
cowork-to-code-bridge
Use an already-installed, independently verified cowork-to-code bridge to run narrowly approved actions on the user's own macOS, Linux, or WSL2 machine through a local file queue.
counter-offer-response
Draft counter-offer responses for retention. TRIGGERS - Use when user needs help with counter-offer-response related tasks.
continuous-feedback-system
Design continuous feedback systems. TRIGGERS - Use when user needs help with continuous-feedback-system related tasks.