Git Worktrees: Parallel Branch Development Without Clones

Problem: Parallel Branch Work Without Cloning

When you need to develop a feature, run a long-running test suite, and review a colleague's branch all at the same time, the classic workflow forces you to either stash changes, checkout a different branch, or clone the repository again. Each of those options has downsides: stashing can be error-prone, cloning duplicates the entire object database, and switching branches corrupts your working tree state.

Thesis: Worktrees Keep One Object Database, Two Working Trees

Git 2.5 introduced git worktree, a stable feature that lets you create additional working directories that share the same .git directory. The result is:

• Fast checkout – no objects are copied.
• Isolated working trees – each has its own index and HEAD.
• Shared refs and config – all worktrees see the same commit objects.

Managing Worktrees in Practice

Adding a Worktree

From your main repository:

# Ensure you're on the branch you want to base the worktree on
git checkout main

# Add a new worktree in a sibling directory
git worktree add ../feature-branch feature-branch

This creates ../feature-branch containing a clean checkout of the feature-branch branch. The command is instant even for large repos because only metadata is written.

Listing and Locking

Check all active worktrees:

git worktree list

Lock a worktree to prevent accidental pruning or accidental push of a detached HEAD:

git worktree lock ../feature-branch

Unlock when you're done:

git worktree unlock ../feature-branch

Removing a Worktree

When the worktree is no longer needed, remove it without touching the main repository:

git worktree remove ../feature-branch

After removal, the directory can be deleted manually.

Submodules and Recursive Worktrees

Git does not automatically checkout submodules in new worktrees. Run:

git submodule update --init

or, with Git 2.38+, add --recurse-submodules during the add step:

git worktree add --recurse-submodules ../feature-branch feature-branch

Concrete Example: Running Tests While Coding

Assume you're on main and want to run a nightly test suite on test-suite while you work on feature-x:

1. Checkout main and create a worktree for test-suite:

   git checkout main
   git worktree add ../test-suite test-suite
   

2. Start the test suite in ../test-suite (e.g., npm test).

3. Meanwhile, create another worktree for feature-x:

   git worktree add ../feature-x feature-x
   

4. Develop in ../feature-x. Your changes are isolated from the test suite.

5. When the test suite finishes, you can merge its results into main without touching your feature work.

To verify isolation, edit README.md in ../feature-x, stage it, and run git status in ../test-suite – it should report no changes.

Trade-offs and Limitations

• Disk Usage: Each worktree stores its own set of working files. While the object database is shared, a large repo with many worktrees can still consume significant disk space.
• Hooks: Scripts that assume a single working tree may misbehave. Test hooks in a worktree setup before relying on them.
• Submodules: Must be manually updated in each worktree unless using --recurse-submodules.
• Windows Path Issues: Older Git for Windows (<2.30) may hit path-length limits or symlink problems. Enable long paths in Windows settings and use a recent Git release.
• Concurrent Pushes: Pushing a branch that is checked out in another worktree can leave that worktree in a detached HEAD state. Use git worktree lock or coordinate with teammates.

Takeaways & Next Steps

Git worktrees provide a lightweight, fast way to keep multiple branches checked out side-by-side. They're ideal for:

• Running long-running test suites on one branch while coding on another.
• Reviewing a colleague's branch without disturbing your current work.
• Maintaining a hotfix branch alongside ongoing development.

Next steps:

1. Try adding a worktree for a branch you're actively working on.
2. Experiment with git worktree lock to protect critical branches.
3. Integrate worktrees into your CI pipeline by pointing it to a dedicated worktree directory.

With practice, worktrees become a natural part of your Git workflow, eliminating the need for stashing, cloning, or complex branching gymnastics.