Git Worktrees: Manage Multiple Branches Without Stashing or Repeated Checkouts

Overview

A normal Git checkout changes the branch in one working directory. That is convenient for a single stream of work, but it becomes disruptive when you need to pause a feature, review a pull request, reproduce a bug, or apply an urgent fix. Stashing changes can help, but it adds another state to track and may not preserve an in-progress environment exactly as you need it.

A worktree gives a repository another working directory. Each worktree has its own checked-out files, index, and HEAD, while the worktrees generally share the repository's Git objects and references. In practice, you can edit one branch in one directory and test another branch in a neighboring directory without repeatedly checking out branches in the same folder.

A simple layout might look like this:

~/code/shop/             # primary worktree, usually the default branch
~/code/shop-feature/     # feature worktree
~/code/shop-review/      # review or investigation worktree
~/code/shop-hotfix/      # urgent fix worktree

Run these commands from the primary repository unless noted otherwise:

# List existing worktrees
git worktree list

# Create a worktree for an existing local branch
git worktree add ../shop-feature feature/cart-validation

# Create a new branch and worktree from the current commit
git worktree add -b feature/cart-validation ../shop-feature

# Create a worktree from a remote-tracking branch
git worktree add ../shop-review origin/release/2.x

# Remove a clean worktree
git worktree remove ../shop-feature

The path comes before or alongside the branch argument depending on the form you use, so check the command's help on your installed Git version when adapting a command. A useful habit is to run git worktree list before and after creating a worktree so you can confirm which path is associated with which branch.

Checklist by scenario

Starting a parallel feature

1. Start from a clean, known repository. Confirm the primary directory and identify the branch you want to use as the starting point.
2. Choose a predictable sibling path. Keep worktrees outside the primary directory or use a naming convention that makes their purpose obvious.
3. Create the worktree. For a new branch, use git worktree add -b feature/name ../project-feature. For an existing branch, omit -b.
4. Install or link dependencies as appropriate. Separate worktrees may need their own build artifacts, virtual environments, package installations, or generated configuration.
5. Record the active branch. A prompt, directory name, or shell status display can prevent accidental edits in the wrong worktree.

Reviewing a pull request without interrupting current work

1. Run git fetch so the review worktree can use current remote-tracking references.
2. Create a worktree from the review branch or commit, for example git worktree add ../project-review origin/feature/payment-flow.
3. Inspect the code, run tests, and make temporary local changes if needed.
4. If you need to make review fixes, create or check out an appropriate local branch rather than committing directly to a remote-tracking branch.
5. Remove the review worktree when the review is complete, after preserving any useful notes or patches.

Handling an urgent fix

1. Leave the feature worktree untouched so its uncommitted state remains intact.
2. From the main repository, create a hotfix worktree from the branch that should receive the fix: git worktree add -b hotfix/issue-id ../project-hotfix release.
3. Make the smallest appropriate change, run the relevant checks, and commit it.
4. Push or merge the fix according to your team's normal process.
5. Remove the hotfix worktree only after confirming the branch is safely available elsewhere.

Maintaining release branches

For long-running release maintenance, use stable paths such as project-release-2 and project-release-3. List the worktrees before switching branches, document which directory maps to each release line, and avoid making unrelated changes in a release worktree. This arrangement is especially useful when comparing behavior across versions or backporting a focused patch.

What to double-check

• Branch ownership: Git normally prevents the same branch from being checked out in multiple worktrees. If another worktree already owns the branch, use that directory or create a separate branch.
• Working-tree state: Before removal, run git status in the target worktree. Uncommitted changes, untracked files, and ignored build outputs may be important even if they are not part of a commit.
• Configuration differences: Each directory may have different local environment files, dependency caches, generated files, or editor settings. Check how your project handles these before assuming two worktrees behave identically.
• Submodules and nested repositories: If the project uses them, initialize and update them deliberately in each worktree. Their state may not follow the parent directory in the way you expect.
• Build and test output: Prefer worktree-specific output directories when parallel builds could overwrite one another or cause confusing test results.
• Repository metadata: Do not manually delete a worktree directory as your first cleanup method. Use git worktree remove when possible so Git can update its worktree records.

Use git worktree list --porcelain when you need machine-readable details or a clearer view of paths, branches, and detached states. If a directory was deleted outside Git, run git worktree prune after confirming that the directory is genuinely gone and no one else needs it.

Common mistakes

A detached HEAD is not automatically an error. It is useful for testing a specific commit, comparing releases, or reproducing a historical bug. The risk is forgetting that commits made there are not attached to a named branch. If the work becomes valuable, create a branch before leaving the worktree.

Do not use force options simply to make a command succeed. A forced add, move, or removal can discard assumptions that protect another worktree. First identify the branch, path, lock, or uncommitted data involved; then choose the narrowest corrective action.

When to revisit

Review this workflow whenever you begin a new planning cycle, reorganize repository directories, adopt a different build system, or change how local development environments are created. Tooling changes can affect dependency installation, generated files, shell prompts, editor integration, and test output, even when the core Git commands remain familiar.

Use this short pre-flight checklist before creating parallel work:

1. What branches or commits must remain available at the same time?
2. Which directory will own each worktree, and can the names be understood later?
3. Does the project require separate dependencies, environment files, services, or build directories?
4. Will any scripts assume a single repository path or a fixed branch name?
5. What is the cleanup and handoff plan when the task ends?

After the task, run git status in the worktree, confirm commits or patches are pushed or recorded, and then run git worktree list. Remove temporary worktrees deliberately rather than accumulating abandoned directories. For related environment and debugging workflows, see the Docker Compose environment variables and secrets checklist and the API debugging workflow. A consistent worktree routine turns parallel branch work from a source of accidental state changes into a repeatable developer productivity tool.