Switching branches is cheap until your current directory contains an unfinished refactor, a running development server, and uncommitted debugging changes. Then an urgent review or hotfix arrives. Stashing can work, but repeatedly dismantling and rebuilding the same environment wastes time and creates opportunities to restore the wrong state.

git worktree gives one repository multiple working directories. Each linked worktree has its own checked-out branch, index, and working files while sharing the repository's object database and references. This tutorial creates parallel feature, review, and hotfix directories; explains dependency isolation; shows safe cleanup; and covers the errors developers commonly encounter.

When a worktree is better than a stash or clone

A stash temporarily stores changes so one directory can switch context. A second clone creates a fully separate repository and usually downloads or copies Git objects again. A linked worktree occupies the useful middle ground: multiple live directories attached to one repository.

  • Keep a long-running feature and its development server intact while reviewing another branch.
  • Create an isolated hotfix from the production branch without disturbing local changes.
  • Compare two implementations in separate editors or run their test suites side by side.
  • Give a coding agent or automation process a dedicated branch and directory.

Worktrees share commits, refs, and repository configuration, but each has its own HEAD and index. They are not security boundaries. A destructive Git operation or force-push can still affect shared repository state.

Inspect the repository before adding a worktree

Start from the main repository and update remote-tracking references:

cd ~/projects/storefront
git status --short
git fetch --prune origin
git worktree list

The main worktree does not have to be clean to add another one. However, reading git status first prevents confusion about which directory owns uncommitted work. git worktree list shows every attached path, commit, and branch.

Create a new feature worktree

Create a sibling directory and a new branch based on the latest remote development branch:

git worktree add \
  -b feature/checkout-validation \
  ../storefront-checkout \
  origin/development


cd ../storefront-checkout
git status
git branch --show-current

The -b option creates the branch, and the final argument selects its starting point. Using an explicit start point is safer than assuming the current branch is correct. The new directory is immediately usable; there is no second clone step.

Open an existing remote branch for review

Fetch first, then create a local review branch that tracks the contributor's remote branch:

cd ~/projects/storefront
git fetch origin pull/482/head:review/pr-482
git worktree add ../storefront-pr-482 review/pr-482


cd ../storefront-pr-482
npm ci
npm test

For repositories where the branch already exists on origin, you can create a tracking branch directly:

git worktree add --track \
  -b review/payment-copy \
  ../storefront-payment-copy \
  origin/payment-copy

Do not check out an untrusted pull request and execute its scripts on a production machine or a workstation that holds valuable credentials. Worktrees isolate files, not processes, secrets, or permissions.

Create a hotfix without touching unfinished work

cd ~/projects/storefront
git fetch origin main
git worktree add -b hotfix/tax-rounding \
  ../storefront-hotfix origin/main


cd ../storefront-hotfix
npm ci
npm test
git push -u origin hotfix/tax-rounding

Your original feature directory keeps its files, branch, editor state, and running processes. After the hotfix merges, return to the main repository and remove the linked worktree cleanly.

Keep generated files and dependencies isolated

Each worktree has separate working files, so package directories such as node_modules, Python virtual environments, build outputs, and local environment files are separate too. That is normally desirable: one branch cannot silently reuse dependencies installed for another branch.

cd ../storefront-checkout
cp ../storefront/.env.example .env.local
npm ci
npm run dev -- --port 3001

Use a different port, database schema, queue namespace, and cache prefix when two copies run simultaneously. Never copy a production secret file merely for convenience. Generate development credentials or use your team's secret-management workflow.

Use a detached worktree for disposable experiments

If you only need to inspect or benchmark a commit, avoid creating a permanent branch:

git worktree add --detach ../storefront-benchmark v2.8.0
cd ../storefront-benchmark
npm ci
npm run benchmark

A detached HEAD is appropriate for read-only inspection. If the experiment becomes valuable, create a branch before committing long-term work:

git switch -c experiment/faster-search

Remove worktrees safely

Check for changes in the worktree, stop its processes, then remove it through Git:

cd ../storefront-hotfix
git status --short


cd ~/projects/storefront
git worktree remove ../storefront-hotfix
git branch -d hotfix/tax-rounding
git worktree list

git worktree remove refuses when tracked or untracked changes would be lost. Investigate them rather than reaching immediately for --force. If a directory was deleted manually, preview and clean stale administrative records:

git worktree prune --dry-run
git worktree prune

Troubleshooting common worktree errors

“Branch is already checked out”

Git normally prevents the same branch from being checked out in two worktrees because simultaneous edits would make the branch tip and files difficult to reason about. Run git worktree list, use that existing path, or create a new branch. Avoid --force unless you fully understand the shared-ref consequences.

A worktree moved and Git cannot find it

Use git worktree move old-path new-path instead of moving the directory in a file manager. If the main repository or linked directories were already moved, run git worktree repair with the affected paths.

The editor shows the wrong environment

Confirm the terminal's current directory, branch, environment file, runtime version, and listening port. Give editor windows names that include the branch or directory. Separate database and cache state when both applications can write data.

Disk usage grows unexpectedly

Git objects are shared, but dependency folders, build artifacts, and container volumes are not. Remove completed worktrees and run the package manager's normal cache maintenance when appropriate. Do not delete Git administrative files inside .git/worktrees by hand.

Production workflow checklist

  • Fetch and name an explicit start point before creating a worktree.
  • Use sibling directories with predictable names.
  • Assign unique ports, schemas, queues, and cache prefixes.
  • Treat untrusted branches as untrusted code, even in another worktree.
  • Check status and stop local processes before removal.
  • Use git worktree remove, move, and repair rather than manual file operations.
  • Review git worktree list periodically and prune only stale metadata.

Official sources