How Git Worktrees Work

What is a worktree?

A worktree lets you check out multiple branches simultaneously in separate directories — all backed by a single local repository.

Normally, switching branches updates your working directory in place. With worktrees, each branch lives in its own folder. No stashing. No context switching.

.git/

project/main

project-feat/feature

project-fix/hotfix

Why not just clone?

You could clone the repo multiple times. Here's how that compares:

	Multiple Clones	Worktrees
Storage	Duplicates .git + deps	Shares .git
History	Isolated until pushed	Shared immediately
Config	Separate per clone	Shared (remotes, aliases)
Setup	Full clone required	Instant

How does it work?

In your main repo, .git is a directory. In linked worktrees, it's a file pointing back:

bash

$ cat feature-branch/.git
gitdir: /path/to/main/.git/worktrees/feature-branch

Git tracks each worktree in .git/worktrees/. Operations like garbage collection account for all linked trees.

How do I use it?

Create a worktree

$ git worktree add ../feature-dir feature-branch

Create with new branch

$ git worktree add -b new-feature ../feature-dir

List worktrees

$ git worktree list
/path/to/main      abc1234 [main]
/path/to/feature   def5678 [feature]

Remove a worktree

$ git worktree remove ../feature-dir

What is it good for?

Parallel Development

Work on multiple features without stashing or branch-switching.

Code Review

Check out a PR in a separate directory while keeping your work intact.

CI/CD & Agents

Isolated workspaces for automated builds, linting, or AI coding agents.

What should I watch out for?

Branch Exclusivity

You can't check out the same branch in multiple worktrees. Git blocks this to prevent index conflicts.

Manual Deletion

If you rm -rf a worktree directory, the reference persists. Run git worktree prune to clean up.