A Git worktree lets you check out multiple branches into separate directories, so you can review a pull request, handle a hotfix, or continue feature work without repeatedly switching the files in one working tree. This guide provides a reusable checklist for creating, using, updating, and safely removing worktrees.
Overview
A normal Git clone usually has one working directory and one checked-out branch. When you run git switch, Git replaces the files in that directory with the selected branch. A worktree adds another working directory linked to the same local repository. Each worktree has its own checked-out files, index, and working state, while the repository’s object database and most configuration remain shared.
This makes worktrees useful for parallel tasks such as:
- Keeping an unfinished feature open while investigating a production issue.
- Reviewing a pull request without disturbing your current changes.
- Preparing a release or testing a branch against a different environment.
- Working on two related branches without repeatedly stashing files.
Start from the repository’s main directory and create a sibling directory for each additional branch. For a new branch based on your current HEAD, use:
git worktree add -b feature/checkout-ui ../project-checkout-ui
To create a worktree for an existing local branch, specify the branch without -b:
git worktree add ../project-review feature/payment-flow
Git normally prevents the same branch from being checked out in two worktrees at once. That protection is important: two directories writing to the same branch can make the branch’s history and intended changes unclear. Treat each worktree as a separate checkout with its own terminal, editor window, and test context.
Checklist by scenario
Starting parallel feature work
- Confirm the repository is clean, or deliberately record which changes belong to the current worktree with
git status. - Fetch the branch information you need if the starting point is remote:
git fetch origin. - Create the worktree from a known base branch or commit:
git worktree add -b feature/search ../project-search origin/main
- Move into the new directory and verify the branch:
cd ../project-search
git status --short --branch
- Install dependencies or create environment files required by that checkout. Do not assume generated files from another worktree are available.
- Run the project’s normal validation commands before making changes, so setup failures are distinct from code failures.
Handling a hotfix without closing feature work
Leave the feature worktree open and create the hotfix from the intended release or production base:
git fetch origin
git worktree add -b hotfix/timeout ../project-hotfix origin/main
Check the base commit with git log -1 --oneline before editing. This avoids accidentally branching from an unrelated feature branch. When the hotfix is complete, push or merge it according to your team’s normal process, then remove the worktree only after its local changes are no longer needed.
Reviewing a pull request
For a local branch that already exists, create a separate checkout:
git fetch origin
git worktree add ../project-pr feature/payment-flow
Run tests, inspect the diff, and experiment in this directory without changing the branch currently open in your primary worktree. If the review requires a remote-only branch, create a local branch that tracks it, then attach the worktree:
git switch --track -c review/payment-flow origin/payment-flow
git worktree add ../project-payment-review review/payment-flow
Use the branch-creation command in a worktree where that branch is not already checked out. If Git reports that the branch is in use, inspect all worktrees before taking corrective action.
Updating a worktree
A worktree does not automatically update when the remote changes. Enter the relevant directory, check its branch, and fetch or rebase using your team’s agreed workflow:
cd ../project-search
git status --short --branch
git fetch origin
git rebase origin/main
Use merge instead of rebase when that matches the branch policy or when rewriting the branch history would be inappropriate. Resolve conflicts inside the worktree that owns the branch. Before updating, confirm that you do not have uncommitted changes that the operation could complicate.
Inspecting and cleaning up
List every linked checkout, its branch, and its filesystem path:
git worktree list
git worktree list --porcelain
After a branch has been merged and the directory is no longer needed, remove it from the parent repository:
git worktree remove ../project-search
That command is safest because Git can check the worktree before removal. If the directory contains disposable uncommitted changes, an explicit force option may be appropriate, but inspect the status first:
git -C ../project-search status --short
git worktree remove --force ../project-search
Do not use force as a routine cleanup shortcut. It can discard local work.
What to double-check
- Path and branch: Confirm the new directory is where you expect and run
git branch --show-currentinside it. - Base revision: For new work, verify whether the branch should start from
origin/main, a release tag, or another commit. - Local changes: Run
git statusbefore rebase, merge, reset, or removal. A clean status is not required for every operation, but it makes the decision safer. - Environment isolation: Check environment files, ports, databases, caches, generated assets, and dependency directories. Two worktrees may otherwise compete for the same local service or output path.
- IDE context: Open each worktree as its own project window or workspace. Confirm the editor’s selected interpreter, SDK, container, and test configuration match the branch.
- Hooks and ignored files: Worktrees share repository-level data, but ignored files and generated setup may need to be created separately. Check the project’s bootstrap instructions rather than copying secrets between directories.
- Long-lived directories: If a worktree will remain unused for a while, consider
git worktree lockso automated pruning does not treat its path as disposable. Unlock it when it is active again.
Worktrees are also useful alongside other engineering workflow tools. For example, validate configuration changes in the appropriate checkout before deployment, review CI edits with a YAML or workflow validator, and inspect API or infrastructure changes using the relevant project checks. A separate directory prevents unrelated uncommitted work from obscuring those results.
Common mistakes
Trying to check out one branch twice
Git usually blocks this because the same branch cannot safely have two independent indexes. Instead, use the worktree where that branch is already checked out, or create a separate temporary branch from the same commit if parallel changes truly need independent histories. Avoid manually bypassing the safety check unless you understand the consequences.
Deleting the directory with a file manager
Removing a worktree directory directly can leave administrative metadata behind. After an accidental deletion, run:
git worktree prune
Review the worktree list afterward. Prune stale administrative records, not directories containing work you have not inspected.
Running commands from the wrong checkout
It is easy to run a commit, reset, or test command in the parent directory while intending to work on a sibling. Make the path visible in your shell prompt, use pwd, and check git status --short --branch before consequential operations.
Assuming worktrees duplicate everything
A worktree gives you another checkout, not necessarily a complete isolated machine environment. Databases, containers, ports, caches, credentials, and global package stores may still be shared. Define which resources must be unique before running multiple branches simultaneously.
Removing a worktree before preserving local work
Before cleanup, inspect untracked and ignored files where relevant, commit or export anything valuable, and confirm the branch is pushed or merged as intended. A merged branch can still contain useful local test scripts or notes that are not tracked.
When to revisit
Use this checklist whenever you start parallel feature work, switch to an urgent fix, review a pull request, prepare a release, or return to a dormant project. Revisit the setup before seasonal planning cycles or other periods when your team creates many short-lived branches and directories.
Review the workflow when the repository changes its bootstrap commands, dependency manager, container layout, CI process, IDE configuration, or branch policy. Git behavior and editor integrations can also change as tools are upgraded, so test the commands in a non-critical repository after a significant version change. Pay particular attention to worktree creation, removal, locking, pruning, and branch restrictions.
A practical end-of-task routine is:
- Run the final tests and inspect
git status. - Push or merge the branch according to the project workflow.
- Record or discard any remaining local changes deliberately.
- Run
git worktree listand identify directories that are no longer needed. - Remove completed worktrees with
git worktree remove, then usegit worktree pruneonly to clear records left by missing directories. - Keep active long-lived worktrees documented so teammates and automation do not mistake them for stale checkouts.
With those checks in place, Git worktrees become a low-friction way to separate contexts: one directory for focused development, another for review or operations, and a clear cleanup step when the task is complete.