Git Worktrees: Work on Multiple Branches Without Extra Clones

Why Worktrees Matter

When building a large library or a monorepo, you often need to work on several branches at once—review a pull request, patch a bug, and experiment with a new feature—all without cluttering your disk with dozens of clones. Git worktrees give you a single repository that can host multiple working directories, each checked out to a different commit or branch. This keeps disk usage low, shares history and configuration, and lets you switch between workspaces quickly.

How a Worktree Is Structured

A worktree is just a normal directory that contains a working copy of the repository. Internally it points to the main .git directory that lives in the original clone. The directory tree looks like this:

Location	Description
~/repo/.git	Shared Git metadata (objects, refs, config)
~/repo/	Primary working directory (default branch)
~/repo-worktrees/feature-branch/	Worktree checked out to feature-branch
~/repo-worktrees/bugfix/	Worktree checked out to bugfix

Because all worktrees share the same .git directory, operations like git fetch or git pull performed in one tree affect the others. This is a key benefit: you never have to keep multiple clones in sync.

Creating a Worktree: Step‑by‑Step

1. Open a terminal and navigate to your main repository:

   cd ~/repo
   

2. Verify you have Git 2.5+:

   git --version
   # Expect something like git version 2.39.1
   

3. Create a new worktree for the branch you want to work on. The --checkout flag is optional; Git will create the branch if it doesn’t exist.

   git worktree add ../repo-worktrees/feature-branch feature-branch
   

   This command:

   • Creates ../repo-worktrees/feature-branch relative to the repo root.
   • Checks out the feature-branch into that directory.
   • Leaves the main repo untouched.

4. Navigate into the new worktree and confirm the branch:

   cd ../repo-worktrees/feature-branch
   git status
   # Should show "On branch feature-branch"
   

5. Make changes, commit, and push as usual:

   echo "new line" >> README.md
   git add README.md
   git commit -m "Add feature"
   git push origin feature-branch
   

6. Return to the original working directory and verify the commit is visible:

   cd ~/repo
   git log -1
   # The latest commit should be the one from the worktree
   

7. When finished, remove the worktree:

   git worktree remove ../repo-worktrees/feature-branch
   

   This deletes the directory and cleans up references. If you want to keep the directory for later, use --force to keep it.

Practical Use Cases

• Code Review & PRs: Checkout a pull request branch in a separate worktree while you stay on your feature branch.
• CI Build Isolation: CI agents can spin up a worktree for each build job, sharing the same repository data and reducing storage.
• Large Monorepos: Developers can work on different sub‑projects without cloning the entire repo each time.
• Experimental Features: Keep experimental work isolated in a dedicated worktree, preserving the main branch cleanly.

Trade‑offs & Limitations

• One Worktree Per Branch: Git allows only one worktree to be checked out to a given branch at a time. Parallel work on the same branch requires separate clones.
• Shared .git Directory Risks: A mis‑typed git commit in one worktree can affect the state seen in another. Always double‑check the current branch with git status before committing.
• No Nested Worktrees: Git does not support creating a worktree inside another worktree. Attempts will fail with an error.
• Tooling Compatibility: Some IDEs or Git hosting UIs may not detect worktrees correctly, leading to confusing status displays.
• Removal Caveats: Removing the worktree that is the current directory aborts. Switch to a different tree first.

Checking Your Setup

After adding a worktree, you can list all active worktrees with:

git worktree list
# Shows the path, branch, and commit for each tree

Verify that the shared .git directory is still in the main repo and that no extra .git directories appear in the worktree folders. If you see a .git folder inside a worktree, it indicates a mis‑configured detached worktree and can cause conflicts.

Actionable Take‑away

If you regularly juggle work on multiple branches, start using git worktree instead of cloning. It saves disk space, keeps history in one place, and lets you switch contexts with a single cd command. Just remember the one‑branch‑per‑tree rule and keep your tooling in sync.