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.

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.

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

git worktree add ../partners-develop develop

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

Display all active worktrees and their associated branches:

git worktree list

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 is separate from moving the worktree directory. Run this in that worktree:

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

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

git worktree remove ../partners-develop

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

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.

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

• 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.

• Official Git Documentation: git-worktree