Managing Parallel Branches with Git Worktree: A Practical Guide

Why You Need Multiple Working Directories

When you’re juggling feature development, bug fixes, and long‑running CI jobs, the classic “clone‑and‑switch” workflow can become a bottleneck. Switching branches in a single working tree forces you to commit or stash every change, and large monorepos can double the disk footprint if you clone them for each task. Git’s worktree feature solves this by letting you attach several working directories to the same repository, each pointing to a different branch or commit.

Core Idea: One .git, Many Worktrees

At its heart, git worktree keeps the heavy .git directory—containing all history, refs, and configuration—only once. Each additional working directory contains a lightweight .git file that simply points back to the main repository’s metadata. This means:

• Disk usage stays low because the history is shared.
• Each worktree can be checked out to a different branch or commit.
• Operations in one worktree (e.g., a merge) do not interfere with the others until you explicitly push the changes.

Step‑by‑Step Example

1. Verify Git Version
   Run git --version and ensure it is at least 2.5. Older versions lack the worktree command.

   git --version
   # Expected: git version 2.5.0 or newer
   

2. Create a Test Repository
   In a fresh folder:

   mkdir testrepo && cd testrepo
   
   git init
   
   touch file.txt
   
   git add file.txt
   
   git commit -m "init"
   

3. Add a Worktree
   Attach a new directory to the master branch:

   git worktree add ../worktree1 master
   

   Verify that ../worktree1 contains file.txt.
4. Create a Feature Branch Inside the Worktree
   Navigate into the new worktree and create a branch:

   cd ../worktree1
   
   git checkout -b feature
   
   # Make a change
   
   echo "Feature work" >> file.txt
   
   git add file.txt
   
   git commit -m "feature"
   

5. Return to the Main Repo
   Back in testrepo:

   cd ..
   
   git worktree list
   

   You should see an entry for worktree1 pointing to the feature branch.
6. Check Isolation
   Open the original working directory (testrepo) and confirm that file.txt has not been modified by the worktree changes. Only after merging feature into master will the changes propagate.

Benefits in Real Scenarios

• Parallel Development – Work on a hotfix while a feature branch is under review.
• CI/Build Isolation – Spin up a worktree for a long build without blocking the main checkout.
• Feature‑Flag Testing – Keep a flag branch checked out in a separate directory while you continue work on the main line.

Limitations and Cautions

• Single Active Branch per Worktree – Git will not allow two worktrees to check out the same branch simultaneously. Attempting to do so results in a “branch already checked out” error.
• Shared Metadata Risks – Because all worktrees share the same .git directory, a stray git reset --hard in one worktree can affect the others if you’re not careful about which branch you’re on.
• Cleanup Required – Orphaned worktrees can linger if you delete the directory without git worktree remove. Use git worktree prune to clean up stale references.
• Submodule and Remote Variations – Worktrees cannot have separate remote configurations or submodule states; they inherit those from the main repository.

How to Verify Correct Operation

After setting up worktrees, run the following checks:

• git worktree list – ensures each worktree’s path and branch are correct.
• Inspect the .git file inside each worktree; it should contain a relative path pointing back to the main repo’s .git directory.
• Make a trivial change in one worktree, commit, and confirm that the other worktree’s working tree remains unchanged until a merge.
• Run git fsck from the main repo to confirm that the shared history is intact.

When to Use and When to Skip

If you only need to switch between branches quickly, git stash or a lightweight clone might suffice. Use worktree when:

• You need to run long builds or tests on multiple branches concurrently.
• Disk space is a concern and you want to avoid duplicating the entire repository.
• Your workflow requires side‑by‑side editing of distinct branches without committing intermediate states.

Actionable Checklist

1. Confirm Git >= 2.5.
2. Create worktrees with git worktree add <path> <branch>.
3. Always commit or stash before switching contexts.
4. Use git worktree prune regularly to clean orphaned entries.
5. Document worktree usage in your team’s workflow guide to avoid accidental branch conflicts.

With these steps, you can keep your main working directory pristine while still exploring multiple branches or running parallel CI jobs, all without the overhead of full repository clones.