Why Use Worktrees Instead of Stash?

Last updated on

Have you ever run into that dreaded moment: production is on fire, a quick hotfix is needed, and your working tree is full of uncommitted changes? You’ve got options—none of them great:

  • Stash everything: git stash → switch → fix → git stash pop → hope it merges cleanly.
  • Commit a WIP: noisy history, maybe fails CI, and you’ll squash later.

All of these add stress when you just need to ship a fix. There’s a calmer path: keep your current work exactly where it is, and open a fresh checkout in another folder with git worktree. No juggling stashes, no panic about losing changes, and you can work on both things side by side.

What git worktree actually does

git worktree creates another working folder for the same repo. In that second folder you can check out a different branch. Both folders share the same Git object store (history, objects), but each folder has its own files (your working copy).

Think of it like this:

  • Same repo data under the hood, separate folders on disk.
  • Your unfinished work stays safely in Folder A; you do the hotfix in Folder B.
  • You can run two editors/servers at once.
  • You can’t check out the same branch in two worktrees at the same time.
  • It doesn’t copy the package manager’s install directory (e.g., node_modules or vendor) or build outputs—each worktree/folder has its own untracked files.

Result: clean context switching without stashing or risky temporary commits.

Note: The same branch cannot be checked out in two worktrees at once. See the official docs: git worktree docs.

Quick start: do a hotfix without stashing

You’re on feature-x with local changes. Production needs a fix on main.

# you're in /repo on feature-x with uncommitted changes
git worktree add ../repo-main main   # make a second working folder for main
cd ../repo-main

git switch -c hotfix/login-null      # or create branch directly when adding the worktree
# edit files...
git commit -am "fix: handle null login"
git push -u origin hotfix/login-null

# after merging
cd ../repo
git worktree remove ../repo-main
git worktree prune                   # optional cleanup

✅ Your original /repo stays untouched. No stash needed.

Commands you’ll actually use

git worktree list                          # show worktrees
git worktree add ../main-wt main           # checkout main in ../main-wt
git worktree add ../hotfix-wt -b hotfix/x main   # create & checkout a new branch
git worktree remove ../hotfix-wt           # remove a worktree
git worktree prune                         # clean stale metadata

Note: The same branch cannot be checked out in two worktrees at once.

Dependencies & builds

  • A worktree is just another folder for the same repo.
  • Untracked stuff (dependencies, build output, caches) is per folder.
  • In a new worktree, expect to install dependencies and rebuild.
  • Package managers usually help:
    • System-level caches (e.g., OS package caches).
    • Language/tool caches (e.g., npm/pnpm/yarn, pip, Maven/Gradle, Cargo, Go modules).
  • Build/Test outputs live in that worktree’s folder unless you change their paths.

Speed things up

  • If a tool lets you choose a cache directory, point it outside both worktrees (e.g., ../.cache).
  • Use your ecosystem’s incremental builds and caching (TypeScript, compilers, test runners, build systems).
  • Avoid manually linking dependency folders between worktrees; prefer the package manager’s own cache/store.
  • For big projects, consider remote or shared caches (e.g., CI or build-system cache servers).

When to use stash vs worktree


Use git stash when

  • You’re switching branches for a few minutes (tiny fix, quick review).
  • One working folder is enough; you don’t need two servers/editors.
  • You’re okay with temporary, hidden state (a stash stack).

Pros: fastest, no extra folders.
Cons: easy to forget stashes; stash pop can conflict; untracked files aren’t stashed by default (-u); stale/mixed stashes pile up.

Use git worktree when

  • You want a clean checkout without touching your WIP (hotfixes, releases).
  • You need two branches open at once (two editors/servers, side-by-side compare).
  • The context switch will last hours or days (feature + hotfix in parallel).
  • You prefer explicit isolation (separate folder, separate build output).

Pros: no stashing; safer context switches; parallel development; clearer mental model (one folder = one branch).
Cons: extra folder; you’ll install/build in that folder; you can’t check out the same branch in two worktrees (see docs: git worktree docs).

TL;DR

  • Use worktrees to avoid stashing and to work in parallel.
  • Each worktree is a new folder: run install/build there.
  • Speed up builds by moving caches outside both worktrees (TS, ESLint, Vite, etc.).
  • Quick rule of thumb:
    • < 5 minutes, single editor, low risk? → git stash
    • Hotfix/parallel work, want safety? → git worktree