git-worktree-workflow

name	git-worktree-workflow
description	Manage git worktrees for branch isolation. Use when creating feature branches, working on isolated tasks, creating PRs, and cleaning up after merge.
version	1.0.0

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