git-worktrees

Git Worktrees

Manage an isolated worktree for: $ARGUMENTS

When to Use

• Starting feature implementation (keeps main workspace clean)
• Parallel development (multiple features simultaneously)
• Risky experiments (delete worktree if it fails, main untouched)
• Subagent isolation (agents work in worktree, can't pollute main)

Create Worktree

PROJECT_ROOT="$(git rev-parse --show-toplevel)"
PROJECT_NAME="$(basename "$PROJECT_ROOT")"
FEATURE_NAME="{feature-name}"  # kebab-case, no spaces

WORKTREE_DIR="../${PROJECT_NAME}-worktrees/feat-${FEATURE_NAME}"
BRANCH_NAME="feat/${FEATURE_NAME}"

git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR"
cd "$WORKTREE_DIR"

Verify Clean Baseline

After creating the worktree, run the project's test suite:

# Detect and run test command
if [ -f "package.json" ]; then
    npm test
elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
    pytest
elif [ -f "Cargo.toml" ]; then
    cargo test
elif [ -f "go.mod" ]; then
    go test ./...
fi

If tests fail: Fix baseline before starting implementation. Do not proceed with a broken baseline.

During Implementation

• All work happens in the worktree directory
• Commit frequently to the feature branch
• Main workspace remains untouched
• Subagents receive the worktree path, not the main project path

Finish Branch

When implementation is complete, present exactly these 4 options:

Implementation complete. What would you like to do?

1. Merge back to {base-branch} locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Option 1: Merge Locally

BASE_BRANCH="main"  # or detected base
cd "$PROJECT_ROOT"
git checkout "$BASE_BRANCH"
git pull
git merge "$BRANCH_NAME"
# Verify tests pass on merged result
git branch -d "$BRANCH_NAME"
git worktree remove "$WORKTREE_DIR"

Option 2: Push + Create PR

git push -u origin "$BRANCH_NAME"
gh pr create --title "{title}" --body "## Summary
- {changes}

## Test Plan
- [ ] {verification steps}"

Worktree kept until PR merges.