What is git-worktree-workflow?

The git-worktree-workflow skill streamlines parallel development by managing Git worktrees for branch isolation. It enables developers to work on multiple features or bug fixes in separate directories simultaneously without context switching or stashing, while ensuring Claude's AI settings and rules are consistently applied across all environments through automated symlinking.

When should I use git-worktree-workflow?

git-worktree-workflow is useful in the following scenarios: • Parallel Feature Development: Create isolated environments for new features, allowing you to build and test in one directory while keeping the main repository untouched. • Hotfix Management: Quickly address urgent bugs in a dedicated worktree without interrupting or stashing your current progress on a long-term task. • Streamlined PR Workflows: Manage the entire lifecycle of a Pull Request—from creation to branch cleanup—within a dedicated workspace to maintain a clean local environment. • AI Context Synchronization: Automatically maintain consistent AI agent behavior by symlinking .claude configuration files across different worktrees, ensuring the agent understands project rules in every branch.

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

Key Rules

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

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

git-worktree-workflow

When & Why to Use This Skill

Use Cases