Using Git Worktree for Parallel Branch Development

This technical note provides guidance on leveraging git worktree to enable efficient development across multiple branches within a single repository. It addresses common challenges in branch management and offers practical commands, workflows, and considerations for developers.

Motivation for Git Worktree

In a standard Git workflow, a repository directory is limited to checking out a single branch at a time. Switching branches with uncommitted changes requires committing, stashing, or discarding those modifications, which can disrupt productivity.

git worktree addresses this limitation by allowing the creation of multiple working directories linked to the same repository. Each worktree can be checked out to a distinct branch or commit, facilitating parallel development without the overhead of full repository clones.

Core Commands

Creating a Worktree for an Existing Branch

Create a new worktree directory (e.g., ../partners-develop) checked out to an existing branch (e.g., develop):

git worktree add ../partners-develop develop

Creating a Worktree for a New Branch

Create a new branch (e.g., feature/xyz) from an existing branch (e.g., develop) and associate it with a new worktree directory (e.g., ../feature-xyz):

git worktree add ../feature-xyz -b feature/xyz develop

Listing Worktrees

Display all active worktrees and their associated branches:

git worktree list

Renaming / Moving a Linked Worktree

Best: use the built-in move command (updates Git’s internal metadata):

git worktree move /path/to/old-worktree /path/to/new-worktree

If git worktree move isn’t available:

mv /path/to/old-worktree /path/to/new-worktree
git worktree repair /path/to/new-worktree

Note: You cannot move the primary worktree with git worktree move. To rename the main repo folder, just rename the directory:

mv /path/to/repo /path/to/new-repo-name

Renaming the Branch Used by a Worktree

Renaming the branch is separate from moving the worktree directory. Run this in that worktree:

git -C /path/to/worktree branch -m old-name new-name

Removing a Worktree

Delete a linked worktree directory (ensure it’s clean—no uncommitted changes):

git worktree remove ../partners-develop

Pruning & Repairing Worktree Metadata

Clean up stale entries (e.g., directories deleted manually):

git worktree prune

Repair internal metadata after manual moves or mismatches:

git worktree repair /path/to/worktree

Managing Multiple Worktrees

Each worktree functions as an independent checkout with its own working directory and index. For example:

• partners-app/ → feature/14862
• partners-develop/ → develop
• 14862-2/ → feature/14862-2

Within a single worktree, use git switch to change branches. To switch between worktrees, change directories:

cd ../partners-develop
git status

This approach maintains isolation while sharing the underlying .git object database and history.

Transferring Uncommitted Changes Between Worktrees

Worktrees do not share uncommitted changes. To move modifications from one worktree to another, use one of:

1. Stash (simple & safe)

   # in source worktree
   git stash push -m "move to other worktree"
   
   # in target worktree
   cd ../partners-develop
   git stash pop

2. Patch

   # in source
   git diff > /tmp/mypatch.diff
   
   # in target
   cd ../partners-develop
   git apply /tmp/mypatch.diff

3. WIP Commit

   # in source
   git add .
   git commit -m "WIP move changes"
   
   # in target
   cd ../partners-develop
   git cherry-pick <commit-hash>
   
   # optional: undo WIP locally
   git reset HEAD~ --soft

Best Practices and Considerations

• A single branch cannot be checked out in multiple worktrees simultaneously.
• When creating a new branch during worktree add, include -b .
• Prefer git worktree move over raw mv to keep metadata in sync.
• If you do use mv, follow with git worktree repair.
• Remove unused worktrees with git worktree remove and periodically run git worktree prune.
• Renaming a worktree directory ≠ renaming its branch—use git branch -m for branch rename.

References

• Official Git Documentation: git-worktree