Home / Git & collaboration

Git worktrees: many branches at once

Working with Git· part 2 of 2

Gitworktreebranchingworkflow

There's a naming trap here: the "working tree" and git worktree are two different things. One is the folder of files you edit; the other is a power-tool that lets you have several of those at once.

TL;DR

The working tree is your checked-out files — one branch at a time. git worktree breaks that limit: one repository, several folders, several branches live at once, all sharing the same .git. Reach for it when you need two branches simultaneously — a hotfix mid-feature, a PR review, a long build — without stashing your work.

First: the working tree

The working tree (or working directory) is the folder of actual files you see and edit — the checked-out snapshot of one branch. It's one of git's "three trees":

Tree	What it is
Working tree	the files on disk you actually edit
Staging area (index)	changes marked for the next commit (`git add`)
Commit history	the permanent snapshots (`git commit`)

When you git checkout a branch, git rewrites the files in your working tree to match it.

The one-branch limit

Normally one clone = one working tree = one branch checked out at a time. To switch branches you commit or stash your work, then git checkout other-branch — the same folder's files get rewritten. That's disruptive when you're mid-task and need another branch right now.

What git worktree does

git worktree attaches additional working trees to the same repository — each in its own folder, each on a different branch, all sharing the one .git:

Not a second clone — the worktrees share the same history and objects, so they're lightweight.

When you need it

Urgent hotfix mid-feature — you're deep in feature-x with uncommitted work and a prod bug lands. git worktree add ../hotfix main, fix it there, and your feature folder is untouched.
Reviewing a colleague's PR while keeping your own work in place — check out their branch in a separate worktree.
A long build or test on one branch while you keep coding on another.
Comparing two branches side by side in your editor.

You've already seen this

Claude Code isolates an agent's changes using a git worktree under the hood (a .claude/worktrees/… folder) — the exact hotfix-isolation use case, keeping your main working tree undisturbed.

The commands

git worktree

git worktree add ../project-hotfix hotfix   # new folder, hotfix branch checked out
git worktree list                           # see all working trees
git worktree remove ../project-hotfix       # clean up when done

Gotchas

A branch can be checked out in only one worktree at a time — git blocks the same branch in two places so you can't corrupt it.
All worktrees share the one .git, so it's lightweight — not a second clone, and a commit in one is instantly visible to the others.
Remove worktrees you're done with (git worktree remove) so the list stays clean.

Runnable companion example

Clone the repo and open examples/git-collaboration — the analytic rule (ARM + Terraform), the validation scripts, and the GitHub Actions pipeline from this article, ready to run in your own lab. Try it now: python3 scripts/lint_rule.py rules/*.json

← Back to all topics