Since I started using Claude Code more frequently, I kept noticing a “worktree” checkbox popping up whenever I started a session in a Git repository. I had no idea what it meant, so I did what any curious developer would do and started digging. What I found was a Git feature I somehow never came across before: git worktrees.
What Is a Git Worktree?
A Git worktree is an additional working directory linked to the same repository. Normally, one repo equals one working directory. With worktrees, you get multiple working directories, each on its own branch, all sharing the same .git folder and object store.
No cloning. No syncing. No duplicate history. Just separate checkouts of the same repo, living side by side on your filesystem.
Practical Example
Imagine you’re deep in a feature branch. Hours of context loaded into your head, the right files open, the terminal positioned exactly where you need it. Then a message pops up: “Hey, can you take a quick look at that production bug?”
You have two options. You can stash everything, check out main, fix the bug, push, then check your branch back out and hope your mental model survives the round trip. Or you can reach for git worktree and keep both branches checked out simultaneously, in separate directories, without touching a thing.
The Basics
Create a Worktree
git worktree add ../my-repo-hotfix hotfix/service-sync
This creates a new directory at ../my-repo-hotfix with the hotfix/service-sync branch checked out. Your original directory is untouched.
If the branch doesn’t exist yet, create it on the fly:
git worktree add -b hotfix/service-sync ../my-repo-hotfix main
List Your Worktrees
git worktree list
Output looks like this:
/home/work/my-repo 3a8f21c [feat/new-dashboard] /home/work/my-repo-hotfix 7d14bb9 [hotfix/service-sync]
Remove a Worktree
When you’re done:
git worktree remove ../my-repo-hotfix
Or if the directory is already gone:
git worktree prune
Why This Changes How You Work
Context Switching without the Cost
The classic workflow for handling interruptions is stash > checkout > fix > checkout > pop. It works, but it’s lossy. You lose your editor state, your open tabs, your mental context. And if you forget to pop the stash, you’ve buried work.
With worktrees, each task lives in its own directory. Open both in separate editor windows. Switch by pressing Cmd+Tab, not by running git commands.
Running Two Versions Simultaneously
Need to compare the old behavior against your new implementation? Run both:
git worktree add ../my-repo-stable main cd ../my-repo-stable && php -S localhost:8000 # runs on port 8000 cd ../my-repo && php -S localhost:8001 # runs on port 8001
Long-running Processes Don’t Get Killed
Compilation, test suites, dev servers — these often get nuked when you switch branches. With worktrees, the server in your stable branch keeps running while you work on the feature branch in another directory.
Code Review without Disrupting Your Work
git worktree add ../review-pr-1234 origin/feat/pr-1234
Review the code in ../review-pr-1234, run it, poke at it, all without touching your current branch.
Things to Know
Each branch can only be checked out once. Git won’t let two worktrees point to the same branch at the same time. This is intentional — it would be a mess. If you try, you’ll get a clear error.
They share the index. Since all worktrees share one .git folder, your stashes, refs, and tags are visible everywhere. This is a feature, not a bug. You can git stash list from any worktree and see everything.
A Practical Workflow
Here’s how this might look day-to-day:
~/work/
my-repo/ ← main development, feat/dashboard
my-repo-hotfix/ ← hotfix/service-sync (temporary)
my-repo-review/ ← PR review (rotates with whatever needs review)
Each directory is a full working copy. Each has its own vendor directory, build artifacts, and editor state. You move between them by changing directories, not by running git.
When the hotfix ships, git worktree remove ../my-repo-hotfix. When the PR is merged, swap ../my-repo-review to the next one.
Worth Adding to Your Toolkit
Git worktrees won’t replace every workflow. If you’re mostly making sequential commits on a single branch, you don’t need them. But the moment you find yourself context-switching more than a couple of times a day, jumping between a feature, a hotfix, and a code review, the math changes fast.
The setup is one command. The payoff is every distraction becoming cheaper to handle.
Try it the next time a message interrupts you. You might not go back.
