Quick answer: Git worktrees let you check out multiple branches from the same repository into separate working directories. Instead of stashing unfinished changes, switching branches, and restoring your work, you can keep a feature branch, a production hotfix, and a testing branch open at the same time. Each worktree has its own working files and HEAD, while sharing the repository's underlying Git data. This makes worktrees useful for developers who need parallel workflows without maintaining several independent clones.
A developer is halfway through a feature when an urgent production bug arrives. The current working directory contains unfinished code, modified configuration files, and changes that are not ready to commit.
The traditional response is to stash the changes, switch branches, fix the bug, commit the solution, and then return to the original work. That approach works, but it introduces unnecessary context switching and can become inconvenient when several tasks are active at once.
Git worktrees offer another approach. They allow multiple branches from one repository to be checked out into separate directories, so developers can work on different tasks without repeatedly changing the branch in the same directory.
1. What Is a Git Worktree?
A Git worktree is a working directory associated with a Git repository. A repository can have one main worktree and additional linked worktrees.
Each worktree has its own checked-out files, HEAD, and index. This means that different worktrees can represent different branches at the same time.
For example, a project might have the following structure:
projects/
website/
website-feature/
website-hotfix/
website-testing/The first directory can remain on the main development branch. The second can contain a new feature, the third can contain an urgent production fix, and the fourth can be used for temporary testing.
All of these directories can be linked to the same underlying Git repository.
This is different from simply cloning the repository several times. Separate clones generally have separate repository metadata and object storage, while linked worktrees share much of the repository's underlying data.
2. Why Developers Use Worktrees
Git worktrees are useful whenever a developer needs to keep several independent branches available without repeatedly switching the active branch in one directory.
Handling urgent production fixes
Imagine that a developer is building a new dashboard feature. An urgent bug appears in the production branch.
With a worktree, the developer can create a separate directory for the hotfix while leaving the unfinished feature untouched in its original directory.
This reduces the risk of accidentally committing feature changes with the emergency fix.
Working on separate features
A developer may need to switch between frontend work, backend changes, documentation, and tests. Keeping each task in its own directory can make it easier to maintain context.
Testing another branch
Sometimes a bug appears only in a particular branch or release. A separate worktree can be used to inspect that branch without disturbing the current development environment.
Supporting parallel coding agents
When developers use coding agents or multiple automated development sessions, separate worktrees can help isolate their file changes.
One agent can work on a feature, another can investigate a bug, and a developer can review a third branch in a separate directory.
This does not eliminate all coordination problems. Worktrees share repository metadata and references, so teams still need clear branch ownership and merge procedures.
3. Creating Your First Git Worktree
Before using worktrees, make sure Git is installed and that you are working inside a valid Git repository.
Open a terminal in the main project directory and check the repository status:
git statusSuppose you want to create a new feature branch called feature/new-dashboard.
Run:
git worktree add ../website-feature -b feature/new-dashboardThis command performs two actions:
- Creates a new branch named
feature/new-dashboard. - Creates a new working directory at
../website-featureand checks out that branch there.
You can now open the new directory in another editor window.
The original directory remains on its existing branch. You can continue working there while the feature directory contains the new branch.
4. Adding an Existing Branch to a New Directory
You do not always need to create a new branch. If a branch already exists, you can create a worktree for it directly.
git worktree add ../website-hotfix hotfix/productionThis checks out the existing branch named hotfix/production into the new directory.
There is an important restriction: Git normally prevents the same branch from being checked out in more than one worktree at the same time.
If the branch is already active in another worktree, Git will refuse the operation unless you override the protection. This restriction helps prevent conflicting edits to the same branch.
For normal development, avoid forcing the same branch into multiple working directories. Create a separate branch when you need independent work.
5. Listing All Active Worktrees
As the number of worktrees grows, it becomes important to know which branches are active and where their directories are located.
Run:
git worktree listGit displays the main worktree and linked worktrees, including their paths and associated branches.
For scripts and automation, the porcelain format provides structured output:
git worktree list --porcelainThis is useful when building developer tools that need to inspect the state of a repository.
A practical habit is to check the worktree list before creating a new directory. It reduces confusion and helps avoid duplicate task directories.
6. Understanding How Worktrees Share Repository Data
One of the most useful properties of Git worktrees is that they do not behave like completely independent clones.
Linked worktrees share the repository's common Git data. This can reduce duplicated storage and avoid the need to fetch the same repository history repeatedly.
However, each worktree also has private administrative information.
For example, each worktree maintains its own:
- HEAD reference.
- Index or staging area.
- Working directory files.
- Some worktree-specific administrative information.
References such as local branches are generally shared. This is why a branch cannot normally be checked out in two worktrees simultaneously.
Git stores linked worktree administrative information under the main repository's Git directory, inside the worktrees area.
Developers should not manually modify these internal files. Git provides commands for listing, moving, repairing, locking, removing, and pruning worktrees.
7. Worktrees vs. Git Stash
Git stash and Git worktrees solve different problems.
Stash temporarily saves changes from the current working directory so that the developer can switch branches. Worktrees create additional working directories so that multiple branches can remain checked out simultaneously.
| Feature | Git Stash | Git Worktree |
|---|---|---|
| Keeps multiple branches checked out | No | Yes |
| Separate working directory | No | Yes |
| Temporarily saves uncommitted changes | Yes | Not its primary purpose |
| Useful for parallel tasks | Limited | Yes |
| Shares repository data | Same repository | Linked repository data |
Stash remains useful for short interruptions or when you want to temporarily store a set of changes.
Worktrees are more useful when you need to keep multiple tasks active for an extended period.
8. A Practical Parallel Development Workflow
Consider a developer working on a web application with three active tasks:
- Implementing a new dashboard.
- Fixing an authentication bug.
- Testing a release candidate.
The developer can create three worktrees:
git worktree add ../dashboard -b feature/dashboard
git worktree add ../auth-fix -b fix/authentication
git worktree add --detach ../release-test HEADThe first two commands create new branches. The third creates a detached worktree at the current commit.
Each directory can be opened in a separate editor window or terminal session.
The developer can now:
- Work on the dashboard without disturbing authentication code.
- Investigate the authentication issue in a separate directory.
- Run release tests without changing the main working directory.
- Commit each task independently.
- Merge completed branches through the normal project workflow.
This approach is particularly helpful when urgent work arrives unexpectedly.
9. Managing Dependencies and Local Configuration
One of the practical differences between linked worktrees and separate clones is that each worktree has its own working directory.
Files that are not tracked by Git are not automatically shared between worktrees. This includes many dependency folders, local configuration files, temporary build outputs, and development artifacts.
For example, a JavaScript project may have a separate node_modules directory in each worktree. That can increase disk usage, but it also prevents one task from accidentally overwriting another task's generated files.
Some teams use shared dependency caches to reduce repeated downloads. This can be efficient, but shared mutable build directories may create conflicts if different branches require incompatible versions.
Local environment files such as .env should be handled carefully. Do not copy secrets into an unsecured shared directory simply to make worktrees easier to use.
Use appropriate secret-management tools, local access controls, and ignored files.
10. Cleaning Up a Worktree
When a task is complete, remove its linked worktree using Git rather than simply deleting its directory manually.
git worktree remove ../website-featureGit normally removes only clean worktrees. If there are uncommitted or untracked files, Git may refuse to remove the directory.
This is a useful safety mechanism. Check the status before deleting a worktree:
git -C ../website-feature statusIf the worktree is clean and no longer needed, remove it using the standard command.
Afterward, you may want to inspect the remaining worktrees:
git worktree list11. What Does Git Worktree Prune Do?
Sometimes a linked worktree directory is deleted outside Git. The repository may still contain administrative information referring to the missing directory.
Git worktree prune removes stale worktree information when the associated working directory is missing and eligible for cleanup.
Use a dry run first:
git worktree prune --dry-runReview the output before running the actual cleanup command:
git worktree pruneDo not treat prune as a general command for deleting active worktrees. Use git worktree remove for normal cleanup.
12. Important Worktree Limitations
Worktrees are useful, but they are not a replacement for every Git workflow.
One branch cannot normally be checked out twice
Git prevents a branch from being active in multiple worktrees at the same time. This helps avoid conflicting changes and accidental commits.
Submodule support has limitations
The official Git documentation notes that multiple checkouts of a superproject have incomplete submodule support and are not recommended in general.
Projects that depend heavily on submodules should test their workflow carefully before adopting worktrees broadly.
Shared repository configuration
By default, much of the repository configuration is shared. Git also supports a worktree-specific configuration extension for cases where different worktrees need separate settings.
That extension can introduce compatibility considerations with older Git versions, so teams should understand the environment before enabling it.
More directories require more organization
Worktrees reduce branch switching, but they can create clutter when developers create directories without a naming convention or cleanup process.
Use predictable paths and remove completed worktrees regularly.
13. When Should You Use Git Worktrees?
Worktrees are especially useful for:
- Developers who regularly handle urgent production fixes.
- Engineers maintaining several long-running branches.
- Teams using parallel coding-agent workflows.
- Maintainers who need to test multiple release branches.
- Developers reviewing code while continuing feature work.
- Contributors who need a clean directory for temporary experiments.
They may be less useful for a small project where developers work on one branch at a time and rarely need parallel tasks.
Frequently Asked Questions
Are Git worktrees the same as Git branches?
No. A branch is a reference to a line of development. A worktree is a working directory where a branch or commit can be checked out.
Do Git worktrees duplicate the entire repository?
Linked worktrees share the underlying repository data, while each has its own working files and per-worktree administrative information.
Can I open two Git worktrees in separate VS Code windows?
Yes. Each worktree is a separate directory and can be opened in its own editor window.
Can I delete a worktree folder manually?
It is safer to use git worktree remove. If a directory has already been deleted manually, git worktree prune can clean up stale administrative information when appropriate.
Conclusion
Git worktrees provide a practical way to manage parallel development without repeatedly switching branches in a single working directory.
They are especially useful when a developer needs to handle urgent fixes, review code, run tests, or work with multiple coding agents while preserving unfinished changes.
The essential commands are simple: git worktree add, git worktree list, git worktree remove, and git worktree prune.
Start with two worktrees and a clear directory naming convention. Once the workflow becomes familiar, it can reduce context switching and make complex development tasks easier to organize.