Git Worktrees: Parallel Development Without Stashing or Re-cloning

The Problem: Context Switching Kills Flow

You're deep in a feature branch when an urgent production bug lands. The usual options are painful: stash your changes (and hope they apply cleanly later), commit a WIP you'll have to amend, or clone the entire repository again. Each approach breaks momentum and clutters your disk or history.

Git worktrees, built in since Git 2.5 (2015), solve this by letting you check out multiple branches simultaneously in separate directories — all linked to the same repository. No stashing, no full re-clones, no duplicated .git objects.

How Worktrees Work Under the Hood

A worktree shares the main repository’s .git directory (objects, refs, config) while maintaining its own working tree, index, and HEAD. The main repo stores a worktrees/ folder with administrative files pointing to each linked worktree; each worktree carries a .git file (not a directory) that points back to the main repo.

Because objects aren’t copied, creating a worktree takes seconds even on large repositories. The command git worktree add ../hotfix main checks out main into ../hotfix almost instantly.

Worked Example: Hotfix While Feature Work Continues

Assume you’re on feature/auth-refactor in ~/proj. A critical bug needs a fix on main.

# From your main repo root
$ git worktree add ../proj-hotfix main
Preparing worktree (new branch 'main')
HEAD is now at a1b2c3d Release v2.1.0

Now ~/proj-hotfix is a clean checkout of main. You fix the bug, commit, and push. Meanwhile ~/proj stays on feature/auth-refactor with your uncommitted changes untouched.

When the hotfix is merged, clean up:

$ git worktree remove ../proj-hotfix
$ git worktree prune   # optional, cleans stale admin entries

The branch and commits remain; only the working directory disappears.

Common Workflows That Benefit

• Parallel test runs: Keep a worktree on main for CI‑like integration tests while you iterate on a feature branch.
• PR review: Check out a colleague’s branch in a worktree to run the code locally without disturbing your workspace.
• Long‑lived release branches: Maintain a release/2.x worktree for backporting fixes while main moves forward.

Trade‑offs and Gotchas

Disk usage: Each worktree duplicates checked‑out files. A 2 GB working tree × 5 worktrees = 10 GB of source files (objects stay shared). Plan accordingly.

Tooling assumptions: Some IDEs, Git GUIs, and pre‑commit frameworks expect a single working directory per repo. You may need to configure them per worktree (e.g., point your IDE to the worktree root, run pre‑commit install inside each worktree).

Shared hooks: Hooks in .git/hooks/ run for all worktrees. If a hook depends on the working‑tree path, use GIT_WORK_TREE or git rev‑parse --show‑toplevel inside the hook script.

Submodules: git worktree add does not auto‑initialize submodules. Run git submodule update --init inside the new worktree after creation.

Not a security boundary: Worktrees share config, remotes, and objects. For true isolation (different credentials, no shared history), use separate clones.

Quick Verification Checklist

1. Confirm Git ≥ 2.5: git --version and git help worktree exists.
2. Create a test worktree: git worktree add ../wt-test feature‑branch.
3. Verify shared objects: git -C ../wt-test cat-file -t HEAD and git cat-file -t HEAD show the same commit hash.
4. Inspect admin links: cat .git/worktrees/feature‑branch/gitdir points to the worktree’s .git file; cat ../wt-test/.git points back to the main repo.
5. Test prune safety: delete the worktree directory manually, then git worktree prune --dry‑run lists it; git worktree prune removes the stale entry.

Start Using Worktrees Today

Next time you’re tempted to stash or re‑clone, run git worktree add instead. It’s a single command that keeps your flow intact, your history clean, and your disk usage predictable. For portable drives or moved repos, Git 2.40+ adds git worktree repair and git worktree lock to handle administrative drift. The feature is stable, widely supported, and eliminates a whole class of context‑switching friction.