Git Worktree

Git worktree is a feature that allows you to check out and work on multiple branches of the same repository simultaneously in separate directories. 

Instead of creating entirely separate repository duplicates using git clone, a worktree gives you a new folder (called a "linked worktree") containing only your project files. All of these folders share a single underlying .git directory. This means your commit history, stashes, and remote configurations stay centralized and perfectly in sync without duplicating disk space.

History of Git Worktrees

The git worktree feature was officially introduced on July 29, 2015, as a first-class feature in Git version 2.5. 

The feature was primarily authored by Git contributor Nguyễn Thái Ngọc Duy, who designed it to solve a major pain point for developers—particularly kernel developers—who faced significant friction when context-switching between large branches. 

While the concept launched in 2015, the command toolkit was expanded gradually over subsequent updates to make it what it is today:

• Git 2.5 (July 2015): The base git worktree add and git worktree prune functionality arrived.
• Git 2.7 (January 2016): The git worktree list command was added to easily view all active paths.
• Git 2.17 (April 2018): The git worktree remove and git worktree move commands were introduced, making manual folder deletion and reference cleaning a thing of the past. 

Interestingly, while the feature existed for a long time, it experienced a massive surge in mainstream developer popularity years later, largely driven by the rise of parallel AI coding agents and modern development environments that thrive on concurrent branch workflows.

Figure 1: Multiple Git worktrees can contain different branches in separate directories while sharing the same underlying Git repository.

Why Use Git Worktrees?

No More Stashing:

If you are mid-feature and an urgent bug fix arises, you don't need to use git stash or create a messy "WIP" commit. You can simply open your bug-fix worktree folder, fix the issue, and leave your original work untouched.

Fast Context Switching:

Switching branches in a massive codebase often triggers time-consuming IDE re-indexing and dependency recompilations. Keeping separate branches in distinct folders prevents this friction. 

Parallel Workflows:

You can easily run a long test suite or a local server build on one branch while continuing to write code on another. As highlighted by users on Stack Overflow, they are also highly effective for simultaneously reviewing a coworker's pull request locally.

Storage Efficiency:

Because they reference the same central repository history, linked worktrees take up much less space than making full separate clones. 

Core Commands

You can manage worktrees using the built-in git-worktree Documentation toolkit: 

Command	What it does
git worktree add <path> <branch>	Creates a new folder at <path> and checks out the specified <branch> into it.
git worktree list	Displays all active worktree paths, their associated branches, and current statuses.
git worktree remove <path>	Safely deletes the designated worktree directory and cleans up its internal Git references.

Important Rules & Limitations

One Branch per Folder:

You cannot check out the exact same branch in more than one worktree at the same time. 

Independent Dependencies:

While Git history is shared, local project dependencies (like node_modules or virtual environments) are not automatically shared. Each worktree folder will require you to run its respective package installation step.