What you will achieve

You will create a Git worktree to check out a second branch in a different directory while keeping your current work intact. The pattern is invaluable for hotfixes, code review, parallel feature work, and long-running comparisons.

The problem

You are deep in feature/checkout when a teammate pings you about a urgent hotfix on main. Stash, switch, fix, switch back, pop the stash - you have lost five minutes and most of your context. Worktrees keep both branches checked out simultaneously.

Step 1: examine the existing repo

cd ~/work/myproject
git worktree list
# /Users/you/work/myproject  abc1234 [feature/checkout]

Step 2: add a worktree for the hotfix

git worktree add ../myproject-hotfix main
# Preparing worktree (checking out 'main')
# HEAD is now at ...

You now have ../myproject-hotfix with main checked out, while your original directory still has feature/checkout.

Step 3: create a new branch in the worktree

cd ../myproject-hotfix
git checkout -b hotfix/cve-2026-1234

Or do it in one command:

git worktree add -b hotfix/cve-2026-1234 ../myproject-hotfix main

Step 4: work in parallel

Open both directories in separate editor windows. Run tests in both. Push from either:

# In the hotfix worktree
cd ../myproject-hotfix
# ...edit, commit...
git push -u origin hotfix/cve-2026-1234

# Back to your original feature work
cd ../myproject
# untouched, exactly where you left off

Step 5: list and inspect

git worktree list
# /Users/you/work/myproject          abc1234 [feature/checkout]
# /Users/you/work/myproject-hotfix   def5678 [hotfix/cve-2026-1234]

Step 6: clean up

When the hotfix is merged:

git worktree remove ../myproject-hotfix

If the directory was deleted manually, prune the metadata:

git worktree prune

How it works

The original repo's .git is the single object store. Each additional worktree has a small .git file pointing at main-repo/.git/worktrees/<name>/. Branches are still shared - the same branch cannot be checked out in two worktrees simultaneously.

Use cases

Reviewing a colleague's PR

gh pr checkout 123 --branch pr-123
git worktree add ../pr-123 pr-123
cd ../pr-123
npm install
npm test

Comparing two release branches

git worktree add ../release-1.4 release/1.4
git worktree add ../release-1.5 release/1.5
diff -ru ../release-1.4/src ../release-1.5/src

Long-running CI builds

git worktree add ./build-linux $SHA
git worktree add ./build-windows $SHA
# parallel builds against the same commit, separate trees

Backups before destructive operations

git worktree add ../backup HEAD
# now risk-free experimentation
git rebase -i HEAD~20

Limitations

• The same branch cannot be in two worktrees - check out a different branch or detached HEAD.
• Hooks may misbehave if they assume a single working tree.
• Submodules can interact strangely with worktrees - test before relying on it.
• Some IDEs do not handle multiple worktrees pointing at one object store gracefully.

Worktree-specific configuration

git -C ../hotfix config core.editor "vim"
# config local to this worktree only

Most config is shared via the main repo's .git/config. Per-worktree overrides go into .git/worktrees/<name>/config.worktree.

Aliases

[alias]
    wt = worktree
    wta = worktree add
    wtl = worktree list
    wtr = worktree remove

The mental model

Picture a single object store with multiple working trees grafted on. Each working tree has its own checkout, index, and HEAD. Object storage, refs, and config are shared. The cost of an additional worktree is microseconds and a few inodes.

The result

Once worktrees are in your toolkit, stash-and-switch feels primitive. Hotfixes, reviews, and comparisons happen in parallel without disturbing your current state. Five minutes of setup repays itself the first time a hotfix lands while you are mid-feature.