git-worktree

Git Worktree Management

Efficiently work on multiple branches simultaneously using Git worktrees.

When to Use

Use this skill when:

• Working on multiple features simultaneously
• Reviewing PRs while working on a feature
• Need to test something on another branch
• Hotfixing production while developing
• Comparing branches side-by-side

What Are Worktrees?

Git worktrees allow you to checkout multiple branches at the same time in different directories.

main project/
├── .git (repository)
├── src/ (main branch)
└── ...

../project-feature-a/ (worktree for feature-a branch)
├── .git (file pointing to main repo)
├── src/
└── ...

../project-hotfix/ (worktree for hotfix branch)
├── .git (file pointing to main repo)
├── src/
└── ...

Benefits:

• No need to stash or commit incomplete work
• Instant branch switching (just cd to directory)
• Each worktree has its own build artifacts
• Can run different versions simultaneously

Basic Commands

Create Worktree

# Create worktree for new branch
git worktree add ../project-feature-a -b feature-a

# Create worktree for existing branch
git worktree add ../project-hotfix hotfix-branch

# Create worktree at specific commit
git worktree add ../project-debug abc123

# Create worktree with detached HEAD
git worktree add --detach ../project-temp

List Worktrees

# List all worktrees
git worktree list

# Output:
# /path/to/main           abc123 [main]
# /path/to/feature-a      def456 [feature-a]
# /path/to/hotfix         ghi789 [hotfix-branch]

Remove Worktree

# Remove worktree after merging branch
git worktree remove ../project-feature-a

# Force remove (if untracked files exist)
git worktree remove --force ../project-feature-a

# Prune deleted worktrees from .git/worktrees
git worktree prune

Move Worktree

# Move worktree to new location
git worktree move ../project-feature-a ../new-location

Workflow Patterns

Pattern 1: Feature Development