Git Worktree Explained: How to Use Add, Remove, and More
By
Liz Fujiwara
•
When a critical bug appears on your release branch while you are refactoring code in a feature branch, the traditional workflow creates friction. Stashing your work, switching branches, fixing the bug, and restoring your stash wastes time and introduces risk. The git worktree command solves this by creating multiple working directories tied to a single repository, so different branches can be checked out simultaneously without context-switching overhead.
By the end, you will understand when to use git worktree instead of cloning or stashing, what trade-offs to watch for, and how to standardize it across your team.
Key Takeaways
Git worktree lets you check out multiple branches from a single clone, speeding up workflows for code review, hotfixes, long-running features, and core commands include git worktree add, list, and remove with practical examples like main, feature/payments-v2, and hotfix/security-patch.
Common scenarios include reviewing multiple pull requests, triaging production bugs while keeping a large refactor open, and running CI experiments in parallel, with worktrees sharing one repository object store but maintaining independent directories, indexes (staging areas), and IDE sessions.
Key gotchas are that the same branch cannot be checked out in two worktrees, uncommitted changes can block removal, and submodule behavior is limited.
Git Worktree Basics
Before diving into commands, let’s clarify the key terms. A git repository contains your project’s full history in the .git folder. The working tree refers to the checked-out files on your file system, everything outside that .git directory. The main worktree is created when you run git clone or git init. Linked worktrees are additional directories created via the git worktree command.
Here’s what makes worktrees powerful:
A single .git object store is shared across all worktrees, eliminating duplicate data
Each worktree gets its own working directory at a different location (e.g., repo/, ../repo-hotfix/, ../repo-review-123/)
Every worktree maintains an independent HEAD and index, so branches like main, feature/billing-v3, and hotfix/2026-03-27-incident can be checked out simultaneously
The distinction matters: “working tree” refers to a single directory’s checked-out contents, while “linked worktree” is an additional working tree managed by Git under the same repository. Git stores linked worktree metadata in .git/worktrees/, keeping everything connected.
Note that git worktree has been stable since Git 2.5 (2015), though some features still have experimental corners we’ll revisit later.
Core Commands: Add, List, and Remove Worktrees
Day-to-day usage revolves around three primary commands: git worktree add, git worktree list, and git worktree remove. Let’s walk through each using a running example repository called ai-platform with branches main, feature/experiment-ui, and hotfix/payment-timeout.
The general syntax is git worktree add <path> [<commit-ish>]. Behavior changes depending on whether you pass an existing branch, create a new branch with -b, or use -d for a detached head state.
Using git worktree add in Real Scenarios
Scenario 1: Existing branch, standard directory naming
git worktree add ../ai-platform.worktrees/feature-experiment-ui feature/experiment-ui
This checks out the existing branch into a new working directory. The folder must be empty and will contain the branch’s files.
Scenario 2: Existing branch, different directory name
git worktree add ../experiment-ui-workspace feature/experiment-ui
Useful when organizing by developer name or purpose rather than branch name.
Scenario 3: Create a new branch with -b
git worktree add -b hotfix/payment-timeout ../ai-platform.worktrees/hotfix-payment-timeout origin/main
This spins up an emergency fix environment based on a remote branch without touching your main IDE session. The new branch is created and checked out in one command.
Scenario 4: Detached HEAD with -d
git worktree add -d ../ai-platform.worktrees/prototype 9f3b7c1
Ideal for throwaway experiments or debugging a specific commit. No local branch is created, keeping your branch namespace clean.
For large monorepos, the --no-checkout option lets you apply sparse checkout or scripted setup before files are fully populated. Run git worktree add --no-checkout ../sparse-worktree main, then configure sparse patterns before checkout completes.
Listing and Inspecting Existing Worktrees
Running git worktree list shows all worktrees associated with your repository:
/home/dev/ai-platform abc1234 [main]
/home/dev/ai-platform.worktrees/hotfix-payment-timeout def5678 [hotfix/payment-timeout]
/home/dev/ai-platform.worktrees/review-4821 ghi9012 [feature/experiment-ui]
The output details each path, current commit hash, and branch checked out. You may also see annotations:
[locked] indicates a CI system or release script has locked the worktree to prevent accidental removal
[prunable] marks worktrees whose directories have been manually deleted and need cleanup
For automation and scripts, use git worktree list --porcelain or -z for machine-readable output that internal DevOps or build systems can reliably parse.
Removing Worktrees Safely
After merging a patch and deleting the branch, clean up with:
git worktree remove ../ai-platform.worktrees/hotfix-payment-timeout
This deletes the worktree directory and metadata but not the commit history, so your work remains safe in the repository.
Git refuses to remove a worktree with uncommitted changes by default, showing an error that guides you to commit, stash, or use --force; run git status in the worktree to see what is blocking removal.
The git worktree remove --force <path> command overrides safeguards and should be used cautiously, with teams adopting conventions like always pushing or committing before forcing removal.
If someone manually deletes a worktree directory via the filesystem instead of using worktree remove, stale metadata remains and can be cleaned with git worktree prune; standard practice is to always use Git’s remove command and never OS-level deletion.
Configuration, Options, and Internals that Matter in Practice
Most users only need basic commands, but team-wide adoption benefits from a few configuration settings.
Key options for git worktree add:
-b / -B: Create a new branch (or reset an existing one) in the worktree
--force: Override safeguards like checking for uncommitted changes
--no-checkout: Skip file population for custom sparse checkout setup
-d: Create in detached head state for throwaway experiments
Useful git config settings:
The worktree.guessRemote setting, when enabled, automatically bases new branches on matching remote branches, so running git worktree add feature/search-ranking will check out origin/feature/search-ranking if it exists, reducing mistakes in distributed teams.
The worktree.useRelativePaths setting affects portability, with relative paths making repositories easier to move on disk and absolute paths being explicit but breaking if the project is relocated.
By default, all worktrees share the main repository config file, but enabling extensions.worktreeConfig creates per-worktree config.worktree files for independent settings such as sparse checkout parameters.
Internally, Git stores linked worktrees in $GIT_DIR/worktrees/<name>/ with a private gitdir for each, and tools or scripts should use git rev-parse --git-path rather than manipulating these directories directly.
When to Use Git Worktree vs. Clones or Plain Branch Switching
Teams often juggle three approaches: constantly switching branches with git checkout, cloning the same repo multiple times, or standardizing on git worktree. Each has trade-offs.
Worktrees shine for large monorepos and long running branches: no duplicated object store means less disk usage and faster git fetch operations. A repository with 50GB of history would require 50GB per clone; with worktrees, each additional checkout adds only 2-5GB for the working files.
Scenarios where worktrees excel:
Reviewing multiple pull requests in parallel without losing your current context
Spinning up dedicated environments for performance benchmarking
Running CI experiments or nightly jobs from isolated worktrees
Keeping a large refactor actively working while triaging production issues
Simple branch switching still works for small repos and quick one-off edits. Full clones make sense when teams need completely different remotes or experimental rewrites isolated from the main project.
Branch Switching vs. Clones vs. Worktrees
Approach | Pros | Cons |
Switching branches in one worktree | Simple, familiar to all Git users, no extra directories to manage | Constant context switching, IDE reindexing on each switch, relies on git stash juggling |
Multiple full clones | Total isolation, independent remotes and configs, no branch conflicts | Duplicates GBs of data, slower network operations, more maintenance overhead |
Multiple worktrees | Shared object storage, simultaneous branches for parallel work, good IDE isolation | Single-branch-per-worktree rule, cognitive overhead of tracking multiple directories |
This explicit comparison helps tech leads decide which pattern to encourage in onboarding documentation and internal engineering playbooks.
Team Workflows and Best Practices (with Fonzi Context)
At fast-paced startups and enterprises, parallel feature development and quick hotfixes are routine. Git worktree fits naturally into these workflows.
Organizing worktrees consistently:
Create a dedicated directory structure like ../project-name.worktrees/ with subfolders per branch or task. This gives developers and CI systems predictable paths:
../ai-platform.worktrees/
├──hotfix-2026-03-27-security/
├── review-PR-5821/
└── feature-search-ranking/
Shared aliases and scripts:
Add team-standard aliases to dotfiles or bootstrap scripts:
alias gwta='git worktree add'
alias gwtl='git worktree list'
alias gwtr='git worktree remove'
IDE integration:
Modern tools like VS Code (via Git worktree extensions) and JetBrains IDEs can treat each worktree as a distinct project window, allowing developers to work with multiple branches in separate IDE instances without constant focus switching or manual path juggling.
Disadvantages, Gotchas, and How to Avoid Them
Git worktree is powerful, but understanding its sharp edges early prevents surprises on a busy release night.
Single-branch-per-worktree constraint:
A branch can only be checked out in one worktree at a time. Attempting git worktree add with a branch already in use fails with an error. This is fundamental to Git’s design, allowing the same branch in two worktrees would create race conditions.
Forgotten worktrees:
Developers can forget a worktree exists, leading to “mystery” local changes or unpushed commits. Mitigate this by:
Running git worktree list regularly
Integrating worktree info into shell prompts
Building IDE scripts that highlight active worktrees
Submodule limitations:
Support for submodules in multi-worktree setups remains incomplete as of 2026. Teams relying heavily on submodules should test carefully or consider alternative repository structures.
Stale metadata from manual deletion:
Deleting a worktree directory via the filesystem leaves metadata behind in .git/worktrees/. Fix with git worktree prune or git worktree repair. Always use Git’s remove command instead of OS deletion.
Cognitive overhead:
Multiple top-level directories per repository adds complexity. Mitigate with consistent naming conventions (hotfix-YYMMDD-incident-name, review-PR-XXXXX) and documentation in team wikis.
Conclusion
Git worktree is the most efficient way to work across multiple branches from a single clone, eliminating context-switching, IDE thrash, and risky stash workflows that slow down development teams.
Core commands like git worktree add for feature or hotfix directories, git worktree list for visibility, and git worktree remove for cleanup give teams immediate productivity gains, and combined with settings like worktree.guessRemote and consistent conventions, worktrees become a force multiplier.
For AI-heavy products and complex monorepos, standardizing worktree usage saves hours during incident response and parallel feature development, making teams more resilient and predictable.
FAQ
What is a Git worktree and how does it work?
How do I add and remove a Git worktree?
When should I use Git worktree instead of switching branches?
What’s the difference between the working tree and a linked worktree in Git?
Are there any downsides or gotchas to using Git worktree?
