using-git-worktrees
Isolated workspace creation - creates git worktrees with smart directory selectionand safety verification for parallel feature development.
When & Why to Use This Skill
This Claude skill automates the creation of isolated Git worktrees, allowing developers to manage multiple feature branches simultaneously without the friction of constant context switching. It enhances workflow efficiency by providing smart directory selection, mandatory safety verifications (such as .gitignore checks), and automated environment bootstrapping including dependency installation and baseline test execution.
Use Cases
- Parallel Feature Development: Create independent workspaces to work on multiple features or bug fixes at the same time without polluting the main working directory.
- Safe Implementation Sandboxing: Set up a dedicated environment to execute and test complex implementation plans before merging them into the primary codebase.
- Rapid Context Switching: Switch between different branches instantly by moving between directories instead of using 'git checkout', preserving uncommitted changes in each workspace.
- Automated Workspace Bootstrapping: Automatically detect project types (Node.js, Rust, Python, Go) to install dependencies and verify test baselines in a new worktree.
- Clean Environment Testing: Verify that a new branch builds and passes tests in a fresh environment to ensure no local configuration drift affects the results.
| name | ring:using-git-worktrees |
|---|---|
| description | | |
| trigger | | |
| skip_when | | |
| after | [brainstorming] |
| before | [ring:writing-plans, ring:executing-plans] |
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 ring:using-git-worktrees skill to set up an isolated workspace."
Directory Selection Process
Priority order: (1) Existing .worktrees/ or worktrees/ (2) CLAUDE.md preference (3) Ask user
ls -d .worktrees worktrees 2>/dev/null # Check existing (prefer .worktrees)
grep -i "worktree.*director" CLAUDE.md # Check project preference
If none found, ask: .worktrees/ (project-local, hidden) OR ~/.config/ring/worktrees/<project>/ (global)
Safety Verification
Project-local directories: MUST verify .gitignore before creating: grep -q "^\.worktrees/$\|^worktrees/$" .gitignore
- If NOT in .gitignore: Add it → commit → proceed (fix broken things immediately)
- Why critical: Prevents accidentally committing worktree contents
Global directory (~/.config/ring/worktrees): No verification needed - outside project.
Creation Steps
# 1. Detect project
project=$(basename "$(git rev-parse --show-toplevel)")
# 2. Create worktree (path = $LOCATION/$BRANCH or ~/.config/ring/worktrees/$project/$BRANCH)
git worktree add "$path" -b "$BRANCH_NAME" && cd "$path"
# 3. Auto-detect and run setup
[ -f package.json ] && npm install
[ -f Cargo.toml ] && cargo build
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && poetry install
[ -f go.mod ] && go mod download
# 4. Verify clean baseline (npm test / cargo test / pytest / go test ./...)
If tests fail: Report failures, ask whether to proceed or investigate.
If tests pass: Report: Worktree ready at <path> | Tests passing (<N> tests) | Ready to implement <feature>
Quick Reference
| Situation | Action |
|---|---|
.worktrees/ exists |
Use it (verify .gitignore) |
worktrees/ exists |
Use it (verify .gitignore) |
| Both exist | Use .worktrees/ |
| Neither exists | Check CLAUDE.md → Ask user |
| Directory not in .gitignore | Add it immediately + commit |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
Common Mistakes
| Mistake | Problem | Fix |
|---|---|---|
| Skip .gitignore verification | Worktree contents tracked, pollute git status | Always grep .gitignore first |
| Assuming directory location | Inconsistency, violates conventions | Follow priority: existing > CLAUDE.md > ask |
| Proceeding with failing tests | Can't distinguish new vs pre-existing bugs | Report failures, get permission |
| Hardcoding setup commands | Breaks on different tools | Auto-detect from project files |
Example Workflow
Announce → Check .worktrees/ exists → Verify .gitignore → git worktree add .worktrees/auth -b feature/auth → npm install → npm test (47 passing) → Report ready
Red Flags
Never:
- Create worktree without .gitignore verification (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 .gitignore 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
- ring:executing-plans or ring:subagent-driven-development - Work happens in this worktree