Use Git Worktrees for Parallel Branch Work

Switching branches is the wrong operation when two pieces of work must remain runnable at the same time. A half-finished feature, a production fix, and a review checkout each need their own files, index, and HEAD. Repeatedly stashing and restoring them hides state and makes it easy to test the wrong branch.

Git worktrees provide multiple checked-out directories attached to one repository. The useful mental model is not “several clones.” It is several working contexts that share repository objects and most references while keeping their checked-out files and index state separate.

Understand what a worktree isolates

The git worktree manual states that a repository can support multiple working trees and therefore check out more than one branch at a time. Each linked worktree has its own working directory, index, and HEAD. Commits and branches remain part of the shared repository.

This split has practical consequences:

• Editing or staging a file in one worktree does not edit or stage it in another.
• A commit created in one worktree becomes visible to the others because the object database and references are shared.
• The same branch normally cannot be checked out in two worktrees simultaneously. This protects both directories from advancing one branch independently.
• Repository-level configuration and maintenance can affect every attached worktree.

Build products, dependency directories, local databases, and tool caches are ordinary filesystem state. Whether they are isolated depends on where the project stores them, not on Git. A cache under each worktree is separate; a cache under a shared absolute path is not.

Create a worktree with an explicit purpose

From the primary working tree, first inspect attached worktrees and fetch the current remote state if the task requires it:

git status --short --branch
git worktree list
git fetch origin

To create a new local branch for a fix based on the remote default branch:

git worktree add -b fix/payment-timeout ../project-payment-timeout origin/main

To check out an existing local branch:

git worktree add ../project-review feature/invoice-export

The destination should be an intentional sibling directory, not a temporary name that nobody can identify later. The first form creates fix/payment-timeout; the second attaches an existing branch. Inspect the command's resolved branch and path with git worktree list --porcelain when automation needs machine-readable output.

Avoid --force as a routine response to an error. A refusal can mean the branch is active elsewhere or the administrative record points to a worktree that still matters.

Make each directory independently runnable

A new worktree contains tracked files, not the untracked environment from the primary directory. Recreate only the local state that the branch needs:

• install dependencies using the project's lockfile-preserving command;
• generate local configuration from a credential-free template;
• allocate a distinct development port;
• use a separate disposable database or schema where tests mutate data;
• keep logs and build artifacts inside the worktree or a namespaced cache;
• confirm ignored files do not point at a shared production-like target.

Never copy a credential file as a convenience. Use the team's approved secret delivery mechanism and keep the minimum scope required for the task. Two worktrees running concurrently can otherwise share a token, database, message queue, or port and create failures that look like code defects.

Record the current branch at the start of each terminal session:

git status --short --branch
git rev-parse --show-toplevel
git rev-parse --abbrev-ref HEAD

The directory name is a hint; Git's reported state is the evidence.

Use worktrees for reviews and emergency fixes

For a review, create a disposable local branch rather than checking out an untrusted remote contribution directly into an environment containing broad credentials. Run static inspection before build scripts, and use restricted credentials or no credentials for code from an untrusted source.

For an emergency fix, keep the unfinished feature in its original worktree and create the fix from the exact supported base. This removes the need to stash unrelated edits. It does not remove the need to verify the base commit, test the fix, review the diff, and use the normal release path.

For cross-version testing, linked worktrees can hold a release branch and the current branch side by side. Give each one separate build outputs. Tools that key caches only by repository path or package name may contaminate results unless the branch, lockfile hash, runtime version, and build mode are part of the cache key.

Remove worktrees without leaving stale state

Before removal, confirm that the target worktree has no work that exists only in its index or working directory:

git -C ../project-review status --short --branch
git -C ../project-review log --oneline --decorate -n 5
git worktree list

Then remove a clean, disposable worktree through Git:

git worktree remove ../project-review
git worktree prune --dry-run

Running git worktree remove lets Git check the linked state and update its administrative records. Deleting the directory manually can leave a stale entry. git worktree prune --dry-run reports what pruning would remove without changing it; review that output before running the mutating form.

Use git worktree lock --reason "offline review environment" <path> for a worktree on removable or intermittently mounted storage. A lock prevents automatic administrative pruning when the directory is temporarily unavailable. Unlock it deliberately when the reason no longer applies.

Recognize the boundaries of shared history

Worktrees reduce context switching, but they increase concurrency. A fetch, branch deletion, rebase, or repository maintenance command in one context can change what the others see. Coordinate history rewrites and avoid running cleanup while another worktree is performing a sensitive operation.

The workflow is healthy when every worktree has one named purpose, an observable branch, isolated mutable runtime state, and an owner who will remove or lock it. If the directories become anonymous long-lived clones of activity, the problem has moved rather than disappeared.