Git Worktree Workflow

Overview

Manage git worktrees for branch isolation within a single Claude session. Worktrees allow working on a feature branch in a separate directory while keeping the main repo untouched.

Directory Structure

MainProjectDir/
├── ProjectDirApp/      # Main repo (claude runs here)
│   └── .claude/        # Claude settings & rules
└── ProjectWorkTree/    # Worktree (isolated branch work)
    └── .claude -> ../ProjectDirApp/.claude  # Symlinked

Commands Reference

Create Worktree

# From main repo directory
git worktree add ../WorktreeName -b branch-name

# Symlink Claude settings
ln -s ../CurrentRepoDir/.claude ../WorktreeName/.claude

List Worktrees

git worktree list

Remove Worktree

git worktree remove ../WorktreeName
git branch -d branch-name  # Delete local branch

Workflows

Phase 1: Create Worktree

Step 1: Create worktree with new branch
        git worktree add ../WorktreeName -b feature/my-feature

Step 2: Symlink Claude settings
        ln -s "$(basename $(pwd))"/.claude ../WorktreeName/.claude

Step 3: Verify setup
        git worktree list

Phase 2: Work in Worktree

Step 1: Work on files in ../WorktreeName/
        Use full paths: ../WorktreeName/src/file.ts

Step 2: Commit changes
        cd ../WorktreeName && git add . && git commit -m "message"

Step 3: Push branch
        cd ../WorktreeName && git push -u origin feature/my-feature

Phase 3: Create PR

Step 1: Create pull request
        cd ../WorktreeName && gh pr create --base main --head feature/my-feature

Step 2: Return PR URL to user
        Wait for approval

Phase 4: After Merge - Cleanup

Step 1: Return to main repo
        cd back to original repo

Step 2: Pull latest main
        git pull origin main

Step 3: Remove worktree
        git worktree remove ../WorktreeName

Step 4: Delete local branch
        git branch -d feature/my-feature

Step 5: Verify cleanup
        git worktree list

Guidelines

Do

• Symlink .claude/ directory - never copy
• Use relative paths for symlinks (../RepoName/.claude)
• Cleanup after PR merge (remove worktree + delete branch)
• Work in worktree using full paths from main repo
• Return to main repo before cleanup operations

Don't

• Copy .claude/ directory (breaks updates)
• Use absolute paths for symlinks
• Leave worktrees after merge (clutters disk)
• Delete worktree before pushing changes

Examples

Example: Feature Development

# Create
git worktree add ../myapp-auth -b feature/oauth2
ln -s ../myapp/.claude ../myapp-auth/.claude

# Work (edit files in ../myapp-auth/)
cd ../myapp-auth
git add . && git commit -m "feat: add OAuth2 support"
git push -u origin feature/oauth2

# PR
gh pr create --base main --head feature/oauth2 --title "Add OAuth2" --body "..."

# After merge - Cleanup
cd ../myapp
git pull origin main
git worktree remove ../myapp-auth
git branch -d feature/oauth2

Example: Bugfix

# Create
git worktree add ../myapp-fix -b bugfix/login-issue
ln -s ../myapp/.claude ../myapp-fix/.claude

# Work & PR
cd ../myapp-fix
# ... fix bug, commit, push, create PR ...

# Cleanup after merge
cd ../myapp
git worktree remove ../myapp-fix
git branch -d bugfix/login-issue

Error Handling

Worktree already exists

# Check existing worktrees
git worktree list

# Remove if stale
git worktree remove ../WorktreeName --force

Branch already exists

# Use existing branch instead of -b
git worktree add ../WorktreeName existing-branch

Unmerged changes in worktree

# Force remove (loses uncommitted changes)
git worktree remove ../WorktreeName --force

Installation

Symlink the helper script (do not copy):

ln -s /path/to/skills/development/git-worktree-workflow/scripts/worktree.sh .claude/scripts/worktree.sh