Git Worktrees Part 1
If you’ve ever been deep in debugging a feature branch when someone asks you to quickly review a pull request or fix a production bug, you know the pain. You can’t just switch branches—you’ve got uncommitted changes, half-finished work, and a mental context that will take ten minutes to rebuild when you come back. So you either commit incomplete work with a message like “WIP – will fix later” or you stash everything and hope you remember what you were doing.
There’s a better way. Git worktrees let you check out multiple branches simultaneously, each in its own directory. No more branch switching. No more stashing. No more losing your place.
What Worktrees Actually Are
A worktree is just a working directory connected to your repository. When you clone a repository normally, you get one worktree—the directory where your files live and where git status shows what’s changed. Git worktrees let you create additional working directories, each with its own checked-out branch, all sharing the same underlying repository data.
Think of it this way: your repository is a database of commits, branches, and history. A worktree is a view into that database, showing you one particular branch’s files. With multiple worktrees, you can have multiple views open at the same time.
The key insight is that worktrees share everything except the working directory itself. Commits made in one worktree are immediately visible in all others. Branch updates propagate instantly. But each worktree has its own set of files, its own staging area, and its own checked-out branch.
Why This Changes Everything
The most immediate benefit is eliminating context switching. When you’re working on a feature in one worktree and need to review a PR, you don’t stop what you’re doing. You just cd ../review-worktree and check out the PR branch there. Your feature branch work sits untouched in its directory, exactly as you left it. When you’re done with the review, you cd back and continue where you left off.
This is particularly powerful when you’re working with AI agents or automation. You can have one worktree where an agent is running tests, another where you’re actively developing, and a third where you’re reviewing someone else’s changes. Each workspace operates independently without the chaos of switching branches or managing multiple clones of the repository.
The second major benefit is that worktrees prevent common git footguns. Ever accidentally committed to the wrong branch? Run a destructive rebase when you meant to be on a different branch? Worktrees make it physically obvious which branch you’re on because you’re literally in a different directory. The file path in your terminal shows you exactly where you are.
Getting Started
Here’s what the basic setup looks like. Instead of cloning normally, you start with a bare repository:
git clone --bare git@github.com:user/repo.git repo.git
cd repo.gitA bare repository has no working directory—it’s just the git database. This positions all your worktrees as equals rather than having one “main” directory and several “linked” ones. Now create your first worktree:
git worktree add main mainThis creates a directory called main and checks out the main branch there. The first argument is the directory name, the second is the branch to check out. Add a few more:
git worktree add -b review review
git worktree add -b hotfix hotfixNow you have three directories, all tracking the main branch. Wait—didn’t we say you can’t check out the same branch in multiple worktrees? That’s correct, and that’s where the pattern gets interesting. You don’t actually work directly on main in these worktrees. Instead, you create feature branches:
cd review
git checkout pr/123
cd ../hotfix
git checkout -b fix/urgent-bug hotfixThe worktree directories are just namespaces. What matters is which branch is checked out inside them.
The Core Workflow
Once you have worktrees set up, your daily workflow changes in a subtle but significant way. Instead of using git checkout to switch contexts, you use cd to change directories. This feels weird at first because cd seems too simple for something as important as switching branches. But that simplicity is the point.
When you want to work on a feature, you navigate to its worktree and create a branch. When you want to review something, you navigate to your review worktree and check out that branch. When you need to make a hotfix, you navigate to your hotfix worktree and branch from there. Each context stays isolated and preserved. The mental model shift is from “I have one workspace and I change what’s in it” to “I have multiple workspaces and I move between them.”
What You Need to Know
Each worktree requires its own project setup. If your project has dependencies that need installing, you’ll run npm install or the equivalent in each worktree. This sounds like overhead, but it’s actually a feature—each worktree can have different dependencies installed, matching the branch you’re working on. When you switch between worktrees, you’re not wondering if your node_modules match your current branch state.
Disk space is not a major concern. Worktrees share the git object database, so you’re not duplicating your entire repository history multiple times. You’re just duplicating working directories and the specific files checked out on each branch.
You also need to be aware that git commands run in a worktree context. When you run git status in a worktree, it shows the status of that worktree only. When you commit, you’re committing in that worktree’s context. But branch operations—creating branches, merging, rebasing—affect the shared repository and are visible across all worktrees.
When Worktrees Make Sense
Worktrees aren’t for everyone or every project. They make the most sense when you frequently switch contexts—reviewing PRs, jumping to urgent bugs, managing multiple features simultaneously. If you typically work on one thing at a time until it’s done, traditional branch switching might be simpler.
The sweet spot is when you need to maintain multiple parallel workstreams in a single repository. This could be because you’re collaborating with others and need to review their work frequently. It could be because you’re managing both development and production hotfixes. Or it could be because you’re orchestrating multiple AI agents, each working on different aspects of the codebase simultaneously.
In part two, we’ll dive into the practical patterns for managing these parallel workstreams, keeping them synchronized with your main branch, and merging work back together cleanly.
Leave a Reply