Git Worktree : Managing multiple branches simultaneously

Git worktree is a Git feature that allows you to check out multiple branches at once in different directories, without cloning the repository again. This powerful capability transforms how developers handle parallel development workflows.

The Problem with Traditional Branch Switching

Most developers are familiar with the standard Git workflow: switch branches, work on changes, commit, and switch again. This approach creates friction when you need to:

• Compare code between branches side by side
• Test different features simultaneously
• Apply hotfixes while working on a feature branch
• Run builds on multiple branches without losing your current work state

Traditional solutions involve stashing changes, switching branches, or maintaining multiple repository clones. Each approach introduces overhead and complexity.

What Git Worktree Solves

Git worktree eliminates these pain points by creating additional working directories that share the same Git repository. Each worktree operates independently while maintaining a connection to the central .git directory.

Think of it as having multiple desks in the same office. Each desk has different papers (files) spread out, but they all access the same filing cabinet (Git repository).

Basic Worktree Operations

Creating a New Worktree

# Create worktree for existing branch
git worktree add ../feature-login feature/user-login

# Create worktree with new branch
git worktree add ../hotfix-payment -b hotfix/payment-bug

The first command creates a directory ../feature-login containing the feature/user-login branch. The second creates both a new branch and worktree simultaneously.

Listing Active Worktrees

git worktree list

This shows all worktrees with their paths and current branches:

/home/user/myproject        a1b2c3d [main]
/home/user/feature-login    e4f5g6h [feature/user-login]
/home/user/hotfix-payment   h7i8j9k [hotfix/payment-bug]

Removing Worktrees

# Remove worktree (must be done from main repository)
git worktree remove ../feature-login

# Force removal if worktree has uncommitted changes
git worktree remove --force ../feature-login

Practical Development Scenarios

Scenario 1: Feature Development with Hotfix

You're developing a new feature when a critical bug appears in production:

# Currently working in main worktree on feature branch
git worktree add ../hotfix-critical -b hotfix/critical-fix

# Switch to hotfix directory
cd ../hotfix-critical

# Fix the bug, commit, and push
git add .
git commit -m "Fix critical payment processing bug"
git push origin hotfix/critical-fix

# Return to feature work without losing context
cd ../myproject

Scenario 2: Code Comparison and Testing

Compare implementations across branches without losing your current work:

# Create worktrees for comparison
git worktree add ../old-implementation legacy/payment-system
git worktree add ../new-implementation feature/payment-refactor

# Run tests in parallel
cd ../old-implementation && npm run test
cd ../new-implementation && npm run test

Scenario 3: Multiple Environment Builds

Maintain separate builds for different environments:

git worktree add ../staging-build staging
git worktree add ../production-build production

# Build staging while working on development
cd ../staging-build && npm run build:staging

Worktree Limitations and Considerations

Shared State Elements

Certain Git elements are shared across all worktrees:

• Branches: Checking out the same branch in multiple worktrees is prohibited
• Configuration: Repository configuration affects all worktrees
• Hooks: Git hooks execute from the main .git directory
• Stash: Stash entries are shared across worktrees

Best Practices

Keep worktrees focused: Use worktrees for specific, time-limited tasks rather than permanent parallel development.

Clean up regularly: Remove unused worktrees to maintain a clean working environment:

# Remove worktree and clean up references
git worktree remove ../completed-feature
git worktree prune

Avoid nested worktrees: Don't create worktrees inside other worktrees as this creates confusing repository relationships.

Use descriptive paths: Choose directory names that clearly indicate the branch or purpose.

Worktree vs. Alternatives

Git Worktree vs. Multiple Clones

Worktrees share the object database, saving disk space and keeping branches synchronized. Multiple clones require separate git fetch operations and consume more storage.

Git Worktree vs. Branch Switching

Branch switching requires stashing or committing work in progress. Worktrees maintain independent working states without interruption.

Git Worktree vs. Git Stash

Stashing saves work temporarily but doesn't allow parallel development. Worktrees enable simultaneous work on multiple branches.

Git worktree transforms parallel development from a cumbersome process into a streamlined workflow. By maintaining separate working directories while sharing the repository history, it eliminates context switching overhead and enables truly parallel development workflows. The key to effective worktree usage lies in treating them as focused, temporary workspaces rather than permanent parallel development environments.