using-git-worktrees

name	using-git-worktrees
description	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees in <project_root>/.worktrees

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Always use <project_root>/.worktrees/<branch-name>.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Worktree Location

Worktrees are always created at:

<project_root>/.worktrees/<branch-name>

No other location is used. No user preference is asked.

Safety Verification

MUST verify .worktrees is ignored before creating any worktree:

git check-ignore -q .worktrees

If NOT ignored:

Per Jesse's rule "Fix broken things immediately":

1. Add .worktrees/ to .gitignore
2. Commit the change
3. Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to the repository.

Creation Steps

1. Create Worktree

# Ensure the .worktrees directory exists
mkdir -p .worktrees

# Create worktree with new branch
git worktree add .worktrees/$BRANCH_NAME -b "$BRANCH_NAME"
cd ".worktrees/$BRANCH_NAME"

2. 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

3. 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.

4. Report Location

Worktree ready at <full-path>/.worktrees/<branch-name>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Situation	Action
.worktrees/ not ignored	Add to .gitignore + commit first
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 worktree

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.

[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 .worktrees/ is ignored
• Skip baseline test verification
• Proceed with failing tests without asking
• Place worktrees anywhere other than <project_root>/.worktrees/

Always:

• Use .worktrees/<branch-name> as the worktree path
• Verify directory is ignored before creating worktree
• Auto-detect and run project setup
• Verify clean test baseline

Integration

Called by:

• brainstorming - REQUIRED when design is approved and implementation follows
• subagent-driven-development - REQUIRED before executing any tasks
• executing-plans - REQUIRED before executing any tasks
• Any skill needing isolated workspace

Pairs with:

• finishing-a-development-branch - REQUIRED for cleanup after work complete