What it is: A worktree is a separate, real folder on your computer’s disk containing the actual, checked-out files of one specific branch, linked back to a single, shared underlying Git repository. Using Git’s worktree feature, you can create several of these folders at once — each one showing a different branch, fully checked out and ready to work in — all connected to and sharing the exact same history, without needing several independent copies of the repository.

Why it exists: Ordinarily, a Git repository has exactly one working directory, showing exactly one branch’s files checked out at any given moment — switching branches replaces what’s on disk with that branch’s version. This is perfectly fine for most everyday work, but it becomes a real friction point the moment you need to work on, or even just quickly glance at, more than one branch at the same time. Worktrees exist specifically to remove that friction, letting several branches exist as real, simultaneously usable folders, without the overhead of maintaining several entirely separate repository clones.

Where it’s used: Worktrees are commonly used for quickly handling an urgent bug fix without disturbing in-progress feature work, running a slow test suite against one branch while continuing to develop on another, and comparing behavior between two different branches side by side, among other practical multi-branch scenarios.

Practical example: A developer deep in the middle of a complex, half-finished feature suddenly needs to fix an urgent bug on the main branch. Instead of stashing their in-progress feature work, switching branches, fixing the bug, and switching back, they create a second worktree — a separate folder showing the main branch, fully checked out — fix the bug there, all while their original feature-branch folder remains completely untouched and exactly as they left it.

Before worktrees existed, a developer facing the “urgent bug fix while mid-feature” scenario from Chapter 1 had essentially two imperfect options. The first was to temporarily set aside their in-progress, uncommitted changes using a stashing mechanism, switch branches, handle the urgent matter, switch back, and restore their stashed work — a process that works, but adds real friction and risk, especially if anything unexpected interrupts that careful sequence partway through. The second option was to clone the entire repository a second time into a completely separate folder — functional, but wasteful, since it duplicates the repository’s entire object database on disk, and requires separately keeping two full copies in sync with any new shared history.

Worktrees were introduced specifically to offer a genuinely better third option: multiple, simultaneous working folders, each showing a different branch, all sharing one single, common repository underneath — avoiding both the disruption of constant switching and the wastefulness of full, separate clones.

The core problem worktrees solve: how do you let a developer work on, or simply inspect, more than one branch at the same time, as genuinely separate, simultaneously usable folders on disk, without either disrupting in-progress work through constant switching, or wastefully duplicating an entire repository’s full history for every additional folder needed?

This split — one shared object database and set of branches, but a genuinely separate working directory and staging area per worktree — is exactly what allows several worktrees to coexist safely: they can’t accidentally interfere with each other’s uncommitted, in-progress work, while still fully sharing and benefiting from the same underlying commit history the instant something is actually committed.

flowchart LR
    A["Developer requests a new worktree for a branch"] --> B["Git verifies the branch isn't already checked out elsewhere"]
    B --> C["A new working directory folder is created"]
    C --> D["Files for that branch are checked out into the new folder"]
    D --> E["A new, separate index is created for this worktree"]
    E --> F["The worktree is registered, linked back to the shared repository"]
    

Step by step, in plain language: first, the developer specifies which branch they want checked out in a new worktree, and where the new folder should live. Second, Git checks an important safety rule, covered fully in Chapter 6: the same branch cannot be simultaneously checked out in more than one worktree at once, so Git verifies this branch isn’t already in use elsewhere. Third, Git creates the new folder on disk. Fourth, it checks out that branch’s files into this new folder, exactly as an ordinary branch switch would populate a working directory. Fifth, a new, independent staging area is set up specifically for this worktree, kept separate from any other worktree’s staging area. Finally, this new worktree is registered as linked to the same, shared underlying repository, meaning any commit made here becomes immediately part of the same shared history every other worktree can see and build on.

Notice how the entire urgent-fix detour happened without a single stash, without a single branch switch in the original folder, and without any risk of losing or disturbing the original, uncommitted feature work.

Git enforces a strict rule: the exact same branch cannot be checked out in more than one worktree at the same time. If you try to check out a branch that’s already checked out elsewhere, Git refuses and reports the conflict, rather than allowing it. This restriction exists for a genuinely important reason, not as an arbitrary limitation.

This restriction doesn’t meaningfully limit worktrees’ usefulness in practice, since the entire point is working on genuinely different branches simultaneously — needing the exact same branch open in two places at once is a rare, and generally confusing, situation to actually want in the first place.

Worktrees occupy a genuinely useful middle ground: more capability and less disruption than stashing, but far more efficient and tightly connected than a completely separate clone. Choosing the right tool for a given situation comes down to exactly how much separation and independence the task actually requires.

Some tasks — running a slow, thorough test suite, or building a large application — take real, meaningful time to complete. If you can only have one branch checked out at once, you’re forced to either wait for that process to finish before switching to other work, or interrupt it partway through. With worktrees, a slow test run or build can proceed undisturbed in one worktree’s folder, while genuinely new, separate development work continues simultaneously in another.

Because each worktree has its own genuinely separate working directory, as covered in Chapter 3, anything that exists only as an untracked or ignored file — build artifacts, locally installed dependencies, environment-specific configuration files not committed to the repository — does not automatically appear in a newly created worktree. Only content that’s actually part of Git’s tracked, committed history (or explicitly copied over manually) shows up in a fresh worktree’s folder.

Teams that use worktrees heavily often build a small amount of tooling or a documented checklist around this reality, ensuring a newly created worktree gets whatever untracked setup it needs quickly and consistently, rather than each developer rediscovering this requirement independently every time.

Because Git specifically registers and tracks each active worktree, as covered in Chapter 4, a worktree that’s no longer needed should generally be removed through Git’s own worktree-management commands rather than just manually deleting its folder from the file system. Using Git’s proper removal process cleanly un-registers the worktree and frees up its branch to be checked out elsewhere again, honoring the one-branch-per-worktree rule from Chapter 6.

If a worktree’s folder is deleted manually, outside of Git’s own awareness — say, by directly removing it in a file browser — Git can be left with a stale, “administrative” record of a worktree that no longer physically exists on disk. Git provides a dedicated cleanup step specifically to detect and clear out these leftover, stale references, keeping the repository’s worktree bookkeeping accurate and consistent.

GitHub, as a hosting platform, has no direct concept of “worktrees” at all — worktrees exist entirely on your own computer, as a way of organizing how you locally interact with a repository’s history. When you push commits made from any worktree, GitHub receives and stores those commits exactly as it would from any ordinary, single-checkout local repository; from GitHub’s perspective, there’s no visible difference at all between a commit that came from a worktree and one that came from a conventional, single-folder checkout.

This is worth emphasizing precisely because it distinguishes worktrees from many of the other concepts covered elsewhere in this guide series — release branches, pull requests, GitHub Actions — which do involve genuine, visible coordination on the shared, hosted repository. Worktrees, by contrast, are purely about how one individual developer chooses to organize their own local working environment.

The core trade-off to internalize: worktrees trade a small amount of extra local organization and setup discipline — remembering which folder is which, and re-establishing untracked setup per worktree — for genuinely significant gains in avoiding disruptive branch switching and enabling real, simultaneous multi-branch work.

Because the object database is shared rather than duplicated, as covered in Chapter 3, adding an additional worktree costs only the disk space needed for that branch’s actual checked-out files — not another full copy of the repository’s entire history. For a repository with a large, long history but modestly sized checked-out files, this makes worktrees dramatically more space-efficient than equivalent separate clones, especially as the number of simultaneous worktrees grows.

Ordinary Git operations that inspect or modify history — like viewing commit logs or fetching new updates — generally perform the same regardless of how many worktrees exist, since these operations work against the one, shared object database. Where care is still worth taking is with genuinely resource-intensive parallel tasks, like running several full builds or test suites across different worktrees truly simultaneously, since those consume real, independent system resources (processing power, memory) per worktree, even though the underlying Git data itself remains shared and efficient.

It’s also worth remembering that untracked, worktree-specific files — such as locally generated credentials, configuration, or environment files, covered in Chapter 9 — need to be handled with the same care in every worktree individually as they would in a single, ordinary checkout; nothing about using worktrees changes the underlying best practices around keeping sensitive, untracked local files out of version control and appropriately protected.

Finally, since removing a worktree with uncommitted work can permanently lose that work, as covered in Chapter 10, treating worktree cleanup with the same care as any other operation capable of discarding uncommitted changes is a reasonable, sensible precaution, especially on a worktree that might contain sensitive, not-yet-backed-up experimental work.

The Dedicated-Hotfix-Worktree Pattern keeps one worktree permanently set aside, checked out to the main or release branch, specifically ready for urgent fixes at a moment’s notice — directly mirroring the scenario walked through in Chapter 5.

The Comparison-Pair Pattern deliberately sets up two worktrees side by side specifically to compare behavior, performance, or output between two branches directly and simultaneously, as covered in Chapter 8.

Common anti-patterns to avoid: the Worktree Hoarding pattern described above; the Manual Folder Deletion anti-pattern (deleting a worktree’s folder directly instead of using Git’s proper removal process, leaving stale, confusing administrative records behind, as covered in Chapter 10); and the Assumed-Isolation misunderstanding (believing a worktree provides some kind of security or content isolation from the rest of the repository’s shared history, when in fact, as covered in Chapter 14, it provides none).

You may likeWhat Is Git LFS (Large File Storage)?→

Common mistakes beginners make: trying to check out the same branch in two worktrees at once and being confused by Git’s refusal, without understanding the reasoning covered in Chapter 6; assuming a fresh worktree automatically includes locally installed dependencies or configuration; and manually deleting a worktree’s folder instead of using Git’s dedicated removal process, leaving behind confusing, stale administrative records.