DEV Community

z z
z z

Posted on

You're Using Git Wrong — How Worktrees Will Change Your Workflow Forever

#git #productivity #webdev #beginners

You have a pull request open. Tests are failing. Your PM asks you to fix a production bug — right now.

You have two choices:

  1. Stash your current work, switch branches, fix the bug, switch back, unstash
  2. Clone the entire repo again to a separate folder

Both are terrible. But there's a third option most developers don't know about.

What Are Git Worktrees?

A worktree is a linked copy of your repository that lets you check out a different branch in a separate directory — without switching your current working tree.

# While working on feature/login, create a worktree for a hotfix
git worktree add ../project-hotfix fix/production-crash

# Fix the bug in a SEPARATE directory
cd ../project-hotfix
# ... make changes, commit, push ...
cd ../project

# You're STILL on feature/login. Nothing stashed, nothing lost.
Enter fullscreen mode Exit fullscreen mode

No stashing. No cloning. No context switching overhead.

Why This Is a Superpower

1. Parallel Branches Without the Pain 

# Review a PR without touching your current work
git worktree add ../pr-review feature/new-dashboard
cd ../pr-review
git log --oneline -5  # Check the commits
npm test               # Run the tests
cd ../project
git worktree remove ../pr-review
Enter fullscreen mode Exit fullscreen mode

2. Side-by-Side Comparison

Want to compare your branch against main? Open them in two editor windows:

git worktree add ../project-main main
# Now open ../project/ (your branch) and ../project-main/ (main) side by side
Enter fullscreen mode Exit fullscreen mode

3. CI Debugging Without Stopping Everything 

# Keep working on feature/x while debugging CI on a specific commit
git worktree add ../ci-debug 7a3f9e1
cd ../ci-debug
npm ci && npm test
# ... debug CI failure without touching ../project/
Enter fullscreen mode Exit fullscreen mode

4. Documentation and README Updates

The classic "quick fix while in the middle of something":

git worktree add ../docs-update main
cd ../docs-update
# Edit README, commit, push
cd ../project
git worktree remove ../docs-update
# Back to your feature branch, zero context loss
Enter fullscreen mode Exit fullscreen mode

The Workflow That Changed My Life

Here's my daily workflow now:

# Monday morning: start feature
git checkout -b feat/new-api

# Monday afternoon: urgent hotfix
git worktree add ../hotfix main
cd ../hotfix
git checkout -b fix/crash
# fix, commit, PR
cd ../project
git worktree remove ../hotfix

# Tuesday morning: code review colleague's PR
git worktree add ../review fix/crash
cd ../review
# review, test, approve
cd ../project
git worktree remove ../review

# Back on feat/new-api. Never ran git stash once.
Enter fullscreen mode Exit fullscreen mode

Pro Tips

List all worktrees 

git worktree list
# /home/me/project         (main)
# /home/me/project-hotfix  (fix/crash)
# /home/me/pr-review       (feat/new-dashboard)
Enter fullscreen mode Exit fullscreen mode

Prune stale worktrees

After deleting a worktree directory manually, clean up Git's references:

git worktree prune
Enter fullscreen mode Exit fullscreen mode

Use with VS Code

VS Code works perfectly with worktrees. Open a worktree as a new window:

code ../project-hotfix  # Opens in a new VS Code window
Enter fullscreen mode Exit fullscreen mode

Worktrees on the same branch? Yes you can 

git worktree add --detach ../experiment HEAD~3
# Check out an older commit without affecting branches
Enter fullscreen mode Exit fullscreen mode

Common Pitfalls

Issue Solution
Branch already checked out in another worktree Use git worktree add -b new-branch ../path main to branch off
"fatal: '' already exists" The directory must not exist. Git creates it for you
Worktree uses disk space Slightly more than git clone --shared (objects are linked, working tree is separate)
Can't git checkout a branch in main repo It's already checked out in a worktree. Use the --ignore-other-worktrees flag or switch in the worktree

What About Commit Messages?

Worktrees solve the "context switching" problem. But there's another time sink: writing good commit messages for each branch.

When you're context-switching through multiple worktrees, the last thing you want to do is compose a thoughtful commit message for each one. That's why I built git-copilot — a free CLI tool that reads your staged changes and generates a conventional commit message instantly:

$ git commit -m "$(git-copilot gen)"
✨ feat(api): add user routes and controller
Enter fullscreen mode Exit fullscreen mode

No AI, no API keys, no internet. Pure pattern matching. Free and open-source:

👉 git-copilot on GitHub

For teams that need commit templates, CI/CD output formats, and breaking change tracking, there's a Pro Templates Pack ($9.99).

Do you use git worktrees? What's your favorite workflow with them? Let me know in the comments.

Top comments (3)

Collapse
 
z_z_c01afd7cf4c3764a2c73d profile image
z z •

Great point about the multi-agent use case — that's actually exactly what I've been doing with Hermes Agent. Each worker agent gets its own worktree, which means they can build, test, and verify changes in parallel on the same repo without any conflict. The key insight is that worktrees solve the "workspace isolation" problem that most multi-agent orchestration frameworks either ignore or solve with full repo clones (wasteful). I hadn't thought about the Moonshift angle though — deploying directly from a worktree-per-agent pipeline is clever. Do you handle the merge coordination yourself or does Moonshift have a strategy for that?

Collapse
 
harjjotsinghh profile image
Harjot Singh •

Worktrees are underused and you're right to evangelize them - the stash-dance to switch branches is one of those daily frictions people just accept until they see the alternative. But there's a newer killer use case worth adding: worktrees are how you run multiple AI coding agents in parallel without them stepping on each other. Each agent gets its own worktree (isolated working dir, same repo/history), so agent A refactoring auth can't clobber agent B building the dashboard.

That parallel-isolation is exactly why worktrees matter in agent orchestration - it's the cheapest way to give concurrent agents a clean, conflict-free workspace each. I lean on precisely this in Moonshift (a multi-agent pipeline that ships a prompt to a deployed SaaS) - worktree-per-agent isolation is what lets multiple agents build different parts of the same app concurrently without trampling each other. Great post; the human-workflow win is real and the multi-agent angle is the next frontier for them. Have you tried worktrees for parallel agent runs, or mainly for your own branch-juggling? The agent use case 10x'd how much I rely on them.

Collapse
 
z_z_c01afd7cf4c3764a2c73d profile image
z z •

Great point about multi-agent worktrees! I've been using them mainly for branch-juggling, but the agent isolation angle is a killer feature. Going to try running Claude Code in one worktree while prototyping in another. Do you handle dependency conflicts when two agents modify the same file in different worktrees?