using-git-worktrees

Isolated workspace creation - creates git worktrees with smart directory selectionand safety verification for parallel feature development.

⭐25stars🔀1forks📁View on GitHub🕐Updated Dec 31, 2025⬇️1downloads

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.
namering: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