DEV Community

Cover image for Git worktree — Stop Stashing, Start Working in Parallel
Pedro Arenas
Pedro Arenas

Posted on

Git worktree — Stop Stashing, Start Working in Parallel

#git #productivity #workflow #devtools

Introduction: the pain of branch switching 😤

If you’ve worked with Git long enough, you’ve lived this moment:

You’re deep into a feature. Files are half-written. Tests are failing (on purpose).
Then suddenly:

“Hey, can you quickly fix this hotfix on main?”
“Can you review this PR locally?”

So you do the dance:

git status
git stash
git checkout main
Enter fullscreen mode Exit fullscreen mode

Later…

git checkout feature/my-work
git stash pop
# 💥 conflicts
Enter fullscreen mode Exit fullscreen mode

Context lost. Flow broken. Confidence shaken.

Git has had a solution for this for years — and many developers still don’t use it.

That solution is git worktree.

What is git worktree? 🌳

git worktree lets you check out multiple branches of the same repository at the same time, each in its own directory.

Key idea:

  • One Git repository
  • Multiple working directories
  • Each directory has its own checked-out branch

You’re not cloning the repo again.
You’re not copying history.

You’re just creating another view of the same repository.

Think of it as:
“Parallel checkouts without the pain.”

How git worktree works (conceptually) 🧠

A normal Git repo looks like this:

  • One .git directory (history, objects, refs)
  • One working directory (your files)

With worktrees:

  • Still one .git
  • Multiple working directories
  • Each directory:
    • Is on a different branch
    • Has its own files
    • Is completely isolated from the others

What's shared:

  • Git history
  • Commits
  • Objects

What's isolated:

  • Checked-out branch
  • Working files
  • Uncommitted changes

Mental model:

“Multiple terminals, multiple folders, same repo.”

git worktree vs traditional branch switching ⚖️

Traditional workflow:

  • One working directory
  • One branch at a time
  • Frequent stashing
  • Easy to lose context

With git worktree:

  • No stashing
  • No dirty working tree problems
  • No accidental changes on the wrong branch
  • True parallel work

In short:

  • Branch switching → sequential work
  • Worktrees → parallel work

Practical use cases (real workflows) 🚀

Feature development + hotfix 🚑

You're working on:

feature/auth

Production bug appears on main.

Instead of stashing:

git worktree add ../repo-hotfix main
Enter fullscreen mode Exit fullscreen mode

Now you have:

repo/           → feature/auth
repo-hotfix/    → main
Enter fullscreen mode Exit fullscreen mode

Fix the bug, commit, push — without touching your feature work.

Reviewing a PR locally 🔍

You want to check a teammate's branch:

git worktree add ../repo-pr-123 pr/some-feature
Enter fullscreen mode Exit fullscreen mode

Open it in your editor. Run tests. Explore freely.

Your main work stays intact.

Experiments and spikes 🧪

Trying a risky refactor?

git worktree add ../repo-experiment experiment/refactor-auth
Enter fullscreen mode Exit fullscreen mode

If it works → keep it.
If it doesn’t → delete the worktree.

Zero fear. Zero mess.

Release or QA validation 🧪

Keep a stable branch checked out:

git worktree add ../repo-release release/1.4
Enter fullscreen mode Exit fullscreen mode

Run builds, verify fixes, validate QA
while continuing normal feature work elsewhere.

Step-by-step: using git worktree 🛠️

Create a new worktree

From your main repo:

git worktree add ../my-repo-hotfix main
Enter fullscreen mode Exit fullscreen mode

This:

  • Creates a new directory
  • Checks out main there
  • Links it to the same Git repo

Create a worktree with a new branch 

git worktree add -b feature/payments ../my-repo-payments
Enter fullscreen mode Exit fullscreen mode

Perfect for starting new work.

List all worktrees 

git worktree list
Enter fullscreen mode Exit fullscreen mode

Output looks like:

/path/repo              abc123  feature/auth
/path/repo-hotfix       def456  main
/path/repo-experiment   ghi789  experiment/refactor
Enter fullscreen mode Exit fullscreen mode

Work normally

Inside a worktree:

  • git status
  • git commit
  • git push

Everything behaves exactly like a normal repo.

Remove a worktree (cleanup 🧹)

When you're done:

git worktree remove ../my-repo-hotfix
Enter fullscreen mode Exit fullscreen mode

This:

  • Cleans Git metadata
  • Safely removes the worktree

⚠️ Avoid deleting the folder manually.

Common pitfalls & gotchas ⚠️

  • One branch = one worktree
  • You can't check out the same branch twice
  • Don't delete worktrees manually
  • Always use git worktree remove
  • Shared files
    • .env, node_modules, build outputs may need isolation
    • Consider .env.local or per-worktree configs
  • IDE awareness
    • Your editor might open multiple projects
    • This is usually a feature, not a bug 😉

When git worktree shines — and when it doesn't ✨

It shines when:

  • You juggle features and hotfixes
  • You're frequently interrupted
  • You work on large repos
  • You want clean mental separation

It may not be worth it when:

  • The repo is tiny
  • You only do one task at a time
  • You're still learning Git fundamentals

Conclusion & takeaways 🎯

git worktree isn’t a niche feature.
It’s a productivity multiplier.

Key takeaways:

  • Stop stashing just to switch context
  • Work on multiple branches at the same time
  • Keep your flow, keep your sanity
  • Clean, explicit, parallel work

Once you try it, going back to constant stashing feels… painful.

If this article helped you, try git worktree on your next interruption
and let me know how it changed your workflow 👇

Top comments (0)