Git Worktrees: Manage Multiple Branches from One Clone

Learn how to create isolated working directories for different branches with Git worktrees, covering setup, commands, checks, and recovery steps so you can keep a single clone while editing multiple features simultaneously.

Desired Outcome

Maintain one local Git clone that shares its object database, refs, and configuration, while having separate working directories for different branches. This lets you edit multiple features or experiments in parallel without cloning the repo again, saving disk space and network bandwidth.

Prerequisites

A clean working tree in the main repository (no uncommitted changes). The worktree feature is available from Git 2.5 onward; verify with git --version.
Distinct, writable directories on the same filesystem for each worktree. Avoid mounting separate filesystems if you want shared objects.
Sufficient disk space for the working trees; the objects are shared, so only the checked‑out files duplicate.

Step‑by‑Step Procedure

Check existing worktrees
Run in the main repo:
```
git worktree list
```
This lists all linked worktrees, their paths, and the branch each is on.
Create a new branch and worktree
To start a new feature on a fresh branch:
```
# In the main repo
git branch feature-new
# Create worktree and checkout branch there
git worktree add ../feature-new-worktree feature-new
```
Replace ../feature-new-worktree with the desired absolute or relative path. The command creates the directory, checks out feature-new, and links it to the main repo.
Create a worktree for an existing branch
If you need to edit bug-fix-123 that already exists:
```
git worktree add ../bug-fix-123-worktree bug-fix-123
```
Work in the new directory
Navigate to the worktree path and use Git normally:
```
cd ../feature-new-worktree
# Make changes, commit, push, etc.
```
Remove a worktree when finished
To detach and delete the directory:
```
git worktree remove ../feature-new-worktree
```
Git deletes the folder and cleans the internal bookkeeping. If the directory still exists, you can delete it manually, but you must run git worktree prune later to remove the stale entry.

Expected Checks

After adding, run git worktree list again. The new path should appear with the correct branch.
Inside each worktree, verify the branch: git rev-parse --abbrev-ref HEAD should match the intended branch.
Run git status in each worktree to ensure no uncommitted changes are left when you plan to remove it.
After removal, list worktrees to confirm the entry is gone and the directory is free.

Recovery Options

Force removal of a stuck worktree
If git worktree remove fails because the directory is not empty, use:
```
git worktree remove --force ../broken-worktree
```
This removes the bookkeeping entry regardless of the directory state.
Prune stale entries
After manually deleting a worktree directory, run:
```
git worktree prune
```
This cleans up any orphaned references.
Recover lost commits
Deleting a worktree does not delete commits. If you accidentally delete a branch, check the main repo’s reflog:
```
git reflog show feature-new
```
Locate the lost commit hash and create a new branch: git branch recover .

Important Caveats

Do not edit the same tracked file in two worktrees simultaneously. Git will not detect this and you may end up with conflicting changes.
Worktrees share the same .git/config, hooks, and settings. A change in one affects all.
Worktrees require a recent Git version. On older systems, upgrade or use the traditional clone method.

Practical Verification

After setting up a worktree, the simplest check is:

cd ../feature-new-worktree
git rev-parse --abbrev-ref HEAD

It should output feature-new. Then run git status to confirm the working tree is clean. Repeat for each worktree.

Using Git Worktrees to Work on Multiple Branches from One Clone