Git Worktrees: Work on Multiple Branches Simultaneously

What are worktrees?

Multiple working directories for the same repo, each with a different branch checked out. Work on multiple branches simultaneously without switching.

All operations are CLI-only (no VS Code UI for worktree management)

Essential Commands

Create worktree

# For existing branch
git worktree add ../WORKTREE_FOLDER BRANCH_NAME

# Create new branch + worktree
git worktree add ../WORKTREE_FOLDER -b NEW_BRANCH_NAME

# From remote branch
git worktree add ../WORKTREE_FOLDER origin/BRANCH_NAME

List worktrees

git worktree list

Open in VS Code

# Install code command first: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH"
code ../WORKTREE_FOLDER

Remove worktree

git worktree remove ../WORKTREE_FOLDER

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

Clean up after merge

cd PATH_TO_MAIN_REPO
git worktree remove ../WORKTREE_FOLDER
git branch -d BRANCH_NAME              # Delete local branch
git push origin --delete BRANCH_NAME   # Delete remote branch

Prune deleted worktrees

git worktree prune

Common Workflows

Parallel development

git worktree add ../WORKTREE_1 -b FEATURE_1
git worktree add ../WORKTREE_2 -b FEATURE_2
code ../WORKTREE_1
code ../WORKTREE_2
# Work in parallel, then clean up
git worktree remove ../WORKTREE_1
git worktree remove ../WORKTREE_2

Quick hotfix

git worktree add ../HOTFIX_WORKTREE -b HOTFIX_BRANCH main
cd ../HOTFIX_WORKTREE
# Fix, commit, push
git worktree remove ../HOTFIX_WORKTREE

Review PR

git fetch origin
git worktree add ../REVIEW_WORKTREE origin/PR_BRANCH
code ../REVIEW_WORKTREE
# Review, then clean up
git worktree remove ../REVIEW_WORKTREE

Claude Code Agents with Worktrees

# Automatic isolation - Claude handles everything
"Launch an agent with worktree isolation to implement X"

# Manual setup
git worktree add ../AGENT_WORKTREE -b AGENT_BRANCH
code ../AGENT_WORKTREE
# Launch agent in that window

Best Practices

• Use naming pattern: ../REPO_NAME-BRANCH_NAME
• Keep worktrees adjacent to main repo (not inside it)
• One branch per worktree only
• Use git worktree remove, not manual folder deletion
• Clean up after merging

Troubleshooting

# "code: command not found"
# → Install in VS Code: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH"

# "fatal: invalid reference"
git fetch origin
git worktree add ../WORKTREE_FOLDER origin/BRANCH_NAME

# Worktree folder deleted manually
git worktree prune

# Can't remove - uncommitted changes
git worktree remove --force ../WORKTREE_FOLDER  # Warning: loses changes

# Check current branch
git branch
git worktree list

Structure Example

PARENT_DIRECTORY/
├── REPO_NAME/                    (main worktree - main branch)
├── REPO_NAME-FEATURE_1/        (worktree - feature-1 branch)
└── REPO_NAME-{hotfix}/           (worktree - hotfix branch)

All share the same git history. Commits in any worktree are visible in all worktrees.