Back to Git & Version Control
using-git-worktrees
gitworktreesworkflowdevelopmentproductivityisolationversion controlsuperpowers
Install this skill
npx skills add obra/superpowersWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
The using-git-worktrees skill automates the creation of isolated Git workspaces, enabling developers to modify multiple branches simultaneously without constant stash-and-switch cycles. This skill manages directory structures for these workspaces, ensuring they follow project conventions defined in CLAUDE.md or user preferences. Before setup, it performs mandatory security checks, specifically verifying that local worktree folders are properly added to the repository's ignore list to prevent accidental index pollution. Once initialized, the skill auto-detects the programming stack based on manifest files like package.json or Cargo.toml to install necessary dependencies. It concludes by executing a test suite to ensure the new environment provides a clean, functional baseline before any feature development begins. This process eliminates manual environment configuration while maintaining strict repository integrity.
When to Use This Skill
- •Switching contexts to fix a high-priority bug without abandoning current feature work.
- •Reviewing a colleague's pull request in a side-by-side workspace.
- •Working on a long-running feature branch while keeping the main branch active for hotfixes.
- •Comparing performance or behavior between two different implementation branches simultaneously.
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Set up a worktree for this new feature.
- “I need to work on another branch without losing my current changes.
- “Create a new workspace for the authentication update.
- “Can you initialize an isolated environment for this task?
- “Use git worktrees to help me manage these two branches.
Pro Tips
- 💡Always specify your preferred worktree directory in `CLAUDE.md` (e.g., `.worktrees/`) to ensure consistent, automatic setup and avoid prompts.
- 💡Leverage worktrees for short-lived experiments or spike solutions; it's easier to discard an entire worktree than to clean up a cluttered main repository.
- 💡Combine worktrees with task management tools to keep track of which worktree corresponds to which specific task or bug fix.
What this skill does
- •Prioritizes workspace directory selection using local conventions or project-specific instructions.
- •Validates directory exclusion via git-ignore check to prevent accidental version control tracking.
- •Auto-identifies project types and triggers relevant package installation for Node, Rust, Python, or Go.
- •Performs automated baseline testing to confirm the new branch environment is stable.
- •Handles conditional logic for both project-local and global storage paths.
When not to use it
- ✕When working in a repository with extremely restrictive disk space limits.
- ✕When project-specific automated setup scripts are missing and you require a highly custom environment configuration.
Example workflow
- Announce intention to use the using-git-worktrees skill.
- Locate the workspace directory by checking existing folders or CLAUDE.md directives.
- Verify the directory is correctly ignored by Git; modify .gitignore if necessary.
- Create the new worktree and branch using git worktree add.
- Detect environment requirements and execute necessary installation commands.
- Run tests and report the final path and validation results.
Prerequisites
- –A initialized Git repository.
- –A defined branch to checkout or create.
Pitfalls & limitations
- !Failing to add local worktree directories to .gitignore, which leads to untracked file clutter.
- !Ignoring test suite failures during baseline verification, risking the use of a broken environment.
- !Overwriting existing worktrees if directory naming conventions are not followed correctly.
FAQ
Why is verifying the .gitignore file necessary?
If the worktree folder is not ignored, Git will attempt to track files inside it, leading to messy commits and repository pollution.
Can I choose where my worktrees are stored?
Yes, the skill respects existing project directories, defined locations in CLAUDE.md, or will prompt you for a preference if neither exists.
What happens if my baseline tests fail after setup?
The skill will alert you to the failure immediately and pause to ask whether you wish to proceed or investigate the issues.
Does this skill work for non-standard project structures?
It auto-detects dependencies via common files like package.json or Cargo.toml, but may require manual input if your project uses unique build systems.
How it compares
Unlike manual setup which risks ignoring security best practices like gitignore verification, this skill enforces a standardized safety check and automated dependency installation workflow.
📄 Full skill instructions — original source: obra/superpowers
# 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
**If found:** Use that directory. If both exist,
### 2. Check CLAUDE.md
**If preference specified:** Use it without asking.
### 3. Ask User
If no directory exists and no CLAUDE.md preference:
## Safety Verification
### For Project-Local Directories (.worktrees or worktrees)
**MUST verify directory is ignored before creating worktree:**
**If NOT ignored:**
Per Jesse's rule "Fix broken things immediately":
1. Add appropriate line to .gitignore
2. Commit the change
3. 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
### 2. Create Worktree
### 3. Run Project Setup
Auto-detect and run appropriate setup:
### 4. Verify Clean Baseline
Run tests to ensure worktree starts clean:
**If tests fail:** Report failures, ask whether to proceed or investigate.
**If tests pass:** Report ready.
### 5. Report Location
## Quick Reference
| Situation | Action |
|-----------|--------|
|
|
| Both exist | Use
| 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
### 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
## 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
## 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":
1. Add appropriate line to .gitignore
2. Commit the change
3. 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-ignore before 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
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/using-git-worktrees/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/obra/superpowers/using-git-worktrees/SKILL.md - Cursor:
~/.cursor/skills/obra/superpowers/using-git-worktrees/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/obra/superpowers/using-git-worktrees/SKILL.md
🚀 Install with CLI:npx skills add obra/superpowers
Recommended Rules
View more rules →Git Feature Branch Workflow
WorkflowsGitVersion Control
Create a workflow to start new feature branches synchronized with main. Workflow File: .agent/workflows/start_feature.md ```markdown --- description...
TypeScript Tooling & Ecosystem
TypeScriptToolingProductivity
You are an expert in the TypeScript ecosystem. Key Principles: - Use modern tooling for faster builds - Integrate linting and formatting - Generate t...
Advanced AWS Integration (EventBridge, Step Functions)
AWSIntegrationServerless
You are an expert in advanced AWS integration services and patterns. Key Principles: - Choreography (Events) vs Orchestration (Workflows) - Decouplin...
Recommended Workflows
View more workflows →Automatic commit message generator
GitAIAutomation
--- description: Automatic commit message generator and fast AI-powered commit for all current changes --- // turbo-all This workflow automatically ...
Setup Husky Git Hooks
GitAutomationQuality
--- description: Automate code quality checks with pre-commit and pre-push hooks --- 1. **Install Husky**: - Install husky and lint-staged. // ...
Create GitHub PR Template
GitGitHubTeam
--- description: Standardize pull request descriptions for better code reviews --- 1. **Create Template Directory**: - GitHub looks for templates ...
