use-git-worktree

Git Worktree Management

Create and manage isolated git worktrees for task execution with automatic project setup and merge handling.

Overview

Git worktrees provide complete isolation for task work:

• Changes don't affect main workspace until merge
• Can switch between tasks without stashing
• Clean baseline for each task
• Safe to experiment

Workflow

Step 1: Determine Worktree Directory

Find or create the worktree directory using this priority order:

1. Check for existing directory:

   # Preferred (hidden, less clutter)
   ls -d .worktrees 2>/dev/null
   # Alternative
   ls -d worktrees 2>/dev/null
   

2. Check CLAUDE.md for directive:

   worktree-dir: path/to/worktrees
   

3. Check README.md for configuration: Look for worktree or development setup instructions.

4. Ask user if not found:

   "Where should I create worktrees for isolated task work?

   1. .worktrees/ (Recommended - hidden, less clutter)
   2. worktrees/
   3. Custom location"

Step 2: Verify Directory is Gitignored

Critical: Ensure the worktree directory won't be committed.

git check-ignore -q <worktree-dir>

If not ignored:

• Add to .gitignore with user confirmation
• Report the change

echo "<worktree-dir>/" >> .gitignore

Step 3: Create Branch and Worktree

Determine branch name from task:

• Input: TASK-004 or 4
• Branch: task/TASK-004
• Worktree path: <dir>/TASK-004

Create from current HEAD:

# Get current branch as base
BASE_BRANCH=$(git branch --show-current)

# Create branch and worktree in one command
git worktree add -b task/TASK-NNN <dir>/TASK-NNN

Record context:

• Base branch (for later merge)
• Worktree path
• Task ID

Step 4: Auto-Detect and Run Project Setup

Change to worktree directory and detect project type:

File Present	Setup Command
package.json	npm install or yarn install
Cargo.toml	cargo build
requirements.txt	pip install -r requirements.txt
Pipfile	pipenv install
pyproject.toml	pip install -e . or poetry install
go.mod	go mod download
Gemfile	bundle install
pom.xml	mvn install
build.gradle	./gradlew build