using-git-worktrees

Using Git Worktrees

Overview

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

Core principle: All worktrees go in ./.worktrees + safety verification = reliable isolation.

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

Directory

All worktrees are created under ./.worktrees (project root, hidden directory).

Safety Verification

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored:

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

Why critical: Prevents accidentally committing worktree contents to repository.

Creation Steps

1. Create Worktree

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>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Situation	Action
.worktrees/ 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 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

Always:

• Create worktrees under ./.worktrees
• Verify .worktrees/ is in .gitignore
• Auto-detect and run project setup
• Verify clean test baseline

Integration

Called by:

• brainstorming (Phase 4) - 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