Using Git Worktrees for Parallel Development

Inspired by obra/superpowers, adapted for feature-based workflow.

Overview

Git worktrees let you have multiple branches checked out simultaneously in separate directories. Each worktree is a full working copy with its own branch, dependencies, and state.

When to Use

• Working on multiple independent features at the same time on an existing project
• Need to switch between unrelated tickets without stashing or losing context
• Want isolated workspaces so parallel features don't interfere with each other

When NOT to Use

• Initial MVP builds — work directly on main, there's nothing to protect yet
• Single features — a regular branch is simpler and sufficient
• Sequential phases that build on each other — just commit on main or merge between phases

Setup Flow

1. Verify Clean State

Before creating any worktrees, verify the source branch is clean:

# Ensure we're on the base branch (usually main or develop)
git checkout main
git pull origin main

# Verify clean working tree
git status --porcelain
# If not clean: stash or commit before proceeding

2. Choose Worktree Location

Worktrees are created as sibling directories to the repo within the project root. Example with two features in flight:

~/prj/my-project/
  api/                     # git repo (main branch)
  api-notifications/       # worktree (feature/notifications branch)
  api-billing/             # worktree (feature/billing branch)
  web/                     # git repo (main branch)
  web-notifications/       # worktree (feature/notifications branch)

Naming convention: {repo-name}-{feature-name} for clarity.

3. Create Worktree

# From the repo root
REPO_NAME=$(basename $(pwd))
FEATURE="notifications"

git worktree add "../${REPO_NAME}-${FEATURE}" -b "feature/${FEATURE}"

4. Install Dependencies

After creating a worktree, detect the project type and install dependencies:

cd "../${REPO_NAME}-${FEATURE}"

# Python
if [ -f "pyproject.toml" ]; then
  poetry install 2>/dev/null || pip install -e ".[dev]" 2>/dev/null
elif [ -f "requirements.txt" ]; then
  pip install -r requirements.txt
fi

# Node.js
if [ -f "package-lock.json" ]; then
  npm ci
elif [ -f "yarn.lock" ]; then
  yarn install --frozen-lockfile
elif [ -f "pnpm-lock.yaml" ]; then
  pnpm install --frozen-lockfile
elif [ -f "package.json" ]; then
  npm install
fi

# Flutter/Dart
if [ -f "pubspec.yaml" ]; then
  flutter pub get
fi

5. Verify Clean Baseline

Run the test suite to confirm everything passes before making changes. This is critical — if tests fail before you start, you know it's not your fault.

# Python/Django
if [ -f "pytest.ini" ] || [ -f "pyproject.toml" ]; then
  pytest --tb=short -q
fi

# Node.js/Next.js
if [ -f "package.json" ]; then
  npm test -- --watchAll=false 2>/dev/null || npx jest --passWithNoTests 2>/dev/null
fi

# Flutter
if [ -f "pubspec.yaml" ]; then
  flutter test
fi

If tests fail: Report the failures. Ask whether to proceed anyway or investigate first. Do not silently continue with a broken baseline — that makes verification meaningless later.

If tests pass: Report readiness:

✓ Worktree ready: ../api-notifications
  Branch: feature/notifications
  Base: main (abc1234)
  Tests: 47 passing, 0 failures
  Ready for development

6. Install Skills (if using Polaris)

# From the worktree directory
polaris project --profile django-api

7. Generate VS Code Workspace

Generate a .code-workspace file so all active worktrees are accessible from a single VS Code window.

# From the project root (parent of repos)
PROJECT_DIR=$(pwd)

cat > "${PROJECT_DIR}/dev.code-workspace" << EOF
{
  "folders": [
    { "path": "api", "name": "API (main)" },
    { "path": "api-notifications", "name": "API - Notifications" },
    { "path": "api-billing", "name": "API - Billing" },
    { "path": "web", "name": "Web (main)" },
    { "path": "web-notifications", "name": "Web - Notifications" }
  ],
  "settings": {}
}
EOF

Only include folders that exist. Update this file as worktrees are created and removed.

Open with:

code "${PROJECT_DIR}/dev.code-workspace"

The sidebar shows each worktree as a labeled root with separate SCM panels per worktree.

Working in Worktrees

Switching Between Features

Each worktree is a regular directory. Switch between them like any other project:

cd ../api-notifications   # work on notifications
cd ../api-billing         # switch to billing
cd ../api                 # back to main

Committing and PRs

Commits in a worktree happen on that worktree's branch. Normal git workflow applies:

git add .
git commit -m "feat(notifications): add push notification service"
git push origin feature/notifications
gh pr create --title "feat: add push notifications" \
  --body "Implements notification service and delivery queue."

Cleanup

After a feature is merged and the PR is closed:

# From the main repo
git worktree remove ../api-notifications
git branch -d feature/notifications  # delete local branch
git worktree prune

Listing Active Worktrees

git worktree list
# /home/tyler/prj/my-project/api                    abc1234 [main]
# /home/tyler/prj/my-project/api-notifications       def5678 [feature/notifications]
# /home/tyler/prj/my-project/api-billing              ghi9012 [feature/billing]

Cross-Repo Worktrees

For features that span both backend and frontend repos:

# From the project root (~/prj/my-project/)
cd api
git worktree add ../api-notifications -b feature/notifications

cd ../web
git worktree add ../web-notifications -b feature/notifications

Then generate a single workspace file covering both repos and their worktrees (see step 7 above).

Common Issues

"fatal: is already checked out" — You're trying to create a worktree for a branch that's already checked out somewhere. Use a new branch name.

Shared node_modules/venv — Each worktree has its own working directory but shares .git. Dependency directories (node_modules, .venv, build/) are per-worktree and need separate installs.

IDE confusion — Use the generated .code-workspace file to open all worktrees in a single VS Code window with proper isolation. Avoid opening worktrees individually within the same window without a workspace file.