Most developers know branches. Fewer know about **git worktrees** — a built-in feature that lets you have multiple branches checked out at the same time, each in its own directory, sharing a single repository.

If you’ve ever stashed work to jump on a hotfix, cloned a repo twice to compare branches, or tried running multiple AI agents on the same codebase — worktrees solve all of that.

## The Problem Worktrees Solve

Git normally gives you one working directory. One branch checked out at a time. Want to look at another branch? You `git stash`, `git checkout`, do your thing, then switch back and `git stash pop`. It works, but it’s tedious and error-prone.

The alternative — cloning the repo again — is worse. A remote clone duplicates the entire `.git` object database, and you need a separate `npm install` (or equivalent) for each copy. On a large monorepo, that’s gigabytes of disk and minutes of setup.

Worktrees give you the best of both worlds: multiple checked-out branches with minimal git overhead.

## How Worktrees Work

A worktree is an additional working directory linked to your existing repository. It gets its own branch and file tree, but shares the same `.git` object store.

```
# Create a worktree with a new branch
git worktree add -b feature/auth ../my-repo-auth

# Create one from an existing branch
git worktree add ../my-repo-staging staging
```

After running the first command, you have two directories:

```
my-repo/              ← your original working tree (e.g. on main)
my-repo-auth/         ← new worktree on feature/auth
```

Both are fully functional. You can `cd` into either, run builds, make commits — completely independently. But under the hood, they share the same git history, remotes, and object storage.

## Everyday Use Cases

**Hotfix while mid-feature.** You’re deep into a feature branch when a production bug comes in. Instead of stashing and switching, create a worktree from `main`, fix the bug, push, and delete the worktree. Your feature branch stays untouched.

```
git worktree add -b hotfix/login-crash ../hotfix main
cd ../hotfix
# fix, commit, push
git worktree remove ../hotfix
```

**Comparing branches side by side.** Need to look at how two branches implement the same thing? Check both out as worktrees and open them in separate editor windows.

**Running CI locally on multiple branches.** Test your feature branch and main simultaneously without waiting for one to finish before starting the other.

**Parallel AI agents.** Each coding agent needs its own directory and branch to avoid stepping on each other’s files. Worktrees provide exactly that — isolated working directories with zero duplication.

## The Full Lifecycle

```
# Create
git worktree add -b my-branch ../my-worktree

# List all worktrees
git worktree list

# Remove when done (clean working tree required)
git worktree remove ../my-worktree

# Clean up stale references
git worktree prune
```

That’s it. Four commands cover 99% of worktree usage.

## Gotchas to Know About

**One branch per worktree.** This prevents conflicting writes to the same branch. You can override with `--force`, but in practice each worktree should have its own branch.

**Submodules need extra attention.** Submodules are initialized per-worktree. If your project uses them, you’ll need to run `git submodule update --init` in each new worktree.

**Don’t forget to clean up.** Worktrees are cheap, but stale ones accumulate. Run `git worktree list` periodically and remove ones you’re done with. `git worktree prune` cleans up references to deleted directories.

**Shared gitignored files (like `node_modules`) aren’t shared.** Each worktree has its own working directory, so you’ll need a separate `npm install` per worktree. Some tools work around this with symlinks.

## Key Takeaways

- Git worktrees let you check out multiple branches simultaneously from one repo
- They share the `.git` object store, so creation is near-instant and git overhead is minimal
- Perfect for hotfixes, branch comparison, parallel CI, and multi-agent development
- Four commands: `add`, `list`, `remove`, `prune`
- Built into git — no plugins or extensions needed