If you've ever juggled three feature branches using git stash, you know the drill: stash IDs pile up, you forget what was in each one, and every switch costs you a chunk of mental bandwidth before you can write a single line of code. Git Worktree eliminates that overhead by letting each branch live in its own directory simultaneously — no switching required.
The Problem: git stash Doesn't Scale
The first instinct when you need to jump between branches is git stash. It feels safe — your changes are tucked away, you switch branches, you do your thing, then pop the stash back.
In practice, this breaks down fast. After a day of context-switching, you end up with stash@{0} through stash@{4}, zero memory of what each one contained, and merge conflicts waiting when you pop them. I measured actual recovery time on a Mac Mini running three feature branches in parallel: every single branch switch burned 40+ seconds of mental re-orientation — finding the right file, re-reading where I left off, re-running the test that was last failing.
That's not a workflow problem. That's a structural problem. And git stash doesn't fix structure.
The core issue is that a single working directory can only be one branch at a time. Every "switch" is a teardown and rebuild of your mental state. The fix is to stop switching altogether.
The Fix: One Branch Per Directory
Git Worktree lets you check out multiple branches into separate directories — all sharing the same .git folder. No duplication of history, no second clone. Each directory is a fully functional working tree for its own branch.
Here's the basic setup:
# Attach an existing branch to a new directory
git worktree add ../my-project-auth feature/auth
# Create a new branch and attach it in one command
git worktree add -b feature/payment ../my-project-payment
# See all active worktrees
git worktree list
After running this, ../my-project-auth and ../my-project-payment exist as live, independent working directories. You can open each one in a separate terminal tab (or IDE window). Run a build in one while editing code in the other. No stashing, no switching, no context loss.
Verification — after adding your worktrees, run:
git worktree list
Expected output:
/Users/you/my-project abc1234 [main]
/Users/you/my-project-auth def5678 [feature/auth]
/Users/you/my-project-payment ghi9012 [feature/payment]
Each entry shows the path, the HEAD commit hash, and the branch name. If all three show up clean, you're good to go.
Leveling Up: Claude Code + Worktree for Parallel Agents
This is where things get genuinely interesting. Claude Code v2.1.49+ ships a --worktree flag that spins up an isolated worktree per agent session automatically. You don't have to pre-create anything.
# Launch an agent session in isolated worktree mode
claude --worktree
What this does: each claude --worktree invocation gets its own branch and its own directory. Agent A works on feature/auth, Agent B works on feature/payment. They share the same repository history but never touch each other's files mid-flight.
Wire this into an n8n workflow and you get the full pipeline: parallel code generation → automated tests → PR creation → review request — all without a human touching the branch management. On a Mac Mini cluster, I measured roughly a 2× speedup in net feature throughput compared to serial single-agent work.
The key insight is that agent isolation isn't just a convenience feature — it's the thing that makes parallel agent work safe. Without worktree isolation, two agents modifying the same files concurrently is a recipe for corrupted state. With it, each agent has a clean boundary.
Cleanup: Don't Leave Stale Worktrees Around
Worktrees don't clean themselves up. After you merge a branch and close the terminal, the directory and the .git internal reference both persist. Left unchecked, you end up with zombie worktrees that confuse git status output and waste disk space.
Two commands to know:
# Remove a worktree — deletes the directory AND cleans up .git internals
git worktree remove ../my-project-auth
# If the directory is already gone, clean up only the .git reference
git worktree prune
Make git worktree prune a post-merge habit. I run it right after every git branch -d cleanup pass. Takes two seconds and keeps the repo state clean.
Edge case on macOS: if you're using Spotlight or Time Machine, make sure worktree directories aren't inside iCloud Drive sync folders — the sync daemon can lock files mid-operation and cause worktree remove to fail. Keep worktrees in a local, non-synced path.
Variations and Gotchas
| Scenario | Command | Notes |
|---|---|---|
| Attach existing branch | git worktree add ../path branch-name |
Branch must not already be checked out |
| Create + attach new branch | git worktree add -b new-branch ../path |
Equivalent to git checkout -b |
| Detached HEAD worktree | git worktree add ../path HEAD~3 |
Useful for bisect/debugging |
| List with verbose info | git worktree list --porcelain |
Machine-readable output for scripts |
| Repair broken path | git worktree repair ../new-path |
When directory moves after worktree creation |
One gotcha I hit: you cannot check out the same branch in two worktrees simultaneously. Git enforces this. If you try, you'll get:
fatal: 'feature/auth' is already checked out at '/Users/you/my-project-auth'
The fix is either to use a separate branch (create feature/auth-v2 for a second pass) or to remove the first worktree before adding another on the same branch.
Another gotcha with Claude Code's --worktree flag: the auto-generated branch names follow a timestamp + task slug pattern. If you're feeding these into a CI system that enforces branch naming conventions, you'll need to either configure the naming pattern or rename branches post-creation before the PR opens.
Closing
Git Worktree replaces the branch-switching mental tax with a structural change: one branch, one directory, always. The switch from "switching" to "parallel" is the mindset shift that makes the speed difference real.
Pair it with claude --worktree and you have the foundation for multi-agent parallel development — each agent isolated, each PR independent, no collision handling required.
Start with one: git worktree add ../my-project-experiment feature/experiment. Open it in a new terminal tab. Notice that your main working directory didn't change. That's the whole point.
🐦 Faster updates on X: @baegseungh7061
📚 More in this series: AI Insights
💌 Subscribe: Follow on X or grab the RSS
댓글
댓글 쓰기