Is git worktree Built Into Git? A Brief History

The Original Problem

From 2005 (Git's release) through 2014, the standard way to have two checkouts of the same repo was to clone twice. That doubled the disk usage, slowed down fetches (the two clones did not share objects), and made the “which one is canonical” question awkward.

For years the workaround was a contrib shell script: git-new-workdir. It linked your second working directory into the original .git via a maze of symlinks. It worked. It was also fragile and never made it past contrib status. The community wanted a proper built-in solution. Worktree is what they got.

Timeline of Every Feature That Shipped

1. 2007–2014 · git-new-workdir (contrib script)

   The precursor

   Before there was git worktree there was the contrib/workdir/git-new-workdir shell script. It hand-linked .git internals into a sibling directory. It worked, but it was fragile: dangling symlinks, surprises after a rebase, and zero command-line ergonomics. Worktree replaced this script.

2. March 30, 2015 · Patch series posted

   Duy Nguyen sends v1 of the worktree patches

   Vietnamese contributor Nguyễn Thái Ngọc Duy (Duy Nguyen) posted the first version of the worktree implementation to the Git mailing list. The design merged the lessons from git-new-workdir into a native subcommand with proper ref handling.

3. July 27, 2015 · Git 2.5

   git worktree officially ships

   Git 2.5 included git worktree add, git worktree list, and git worktree prune. The first three subcommands. No move, no lock, no repair. The release notes called it an experimental replacement for git-new-workdir — but it was already production-ready for the common case.

4. January 5, 2016 · Git 2.7

   Listing worktrees gets better

   git worktree list got --porcelain output for scripting. A small but important step: worktree tooling could now be built on top of stable machine-readable output instead of parsing human-readable text.

5. May 31, 2017 · Git 2.13

   git worktree lock arrives

   git worktree lock and unlock shipped. The motivation was external drives and network shares — if your worktree is on a USB drive that is currently unplugged, you do not want git worktree prune to silently nuke it. Lock prevents pruning until you explicitly unlock.

6. July 1, 2017 · Git 2.14

   git worktree move and remove

   Two large additions in the same release. move relocates a worktree to a new path; remove cleanly deletes one. Before this, removing a worktree meant rm -rf the directory and then git worktree prune. The new commands made the lifecycle feel symmetric with add.

7. August 2019 · Git 2.23

   Repair support

   git worktree repair landed. The use case: you moved the main repo or a worktree manually and Git lost track. Repair walks both directions and fixes the cross-references. Before this, a misplaced .git/worktrees entry could only be hand-edited.

8. Mid-2020 onward · —

   IDE integration begins

   VS Code, JetBrains, GitKraken, and Sourcetree start adding worktree UI support. The pattern is consistent: each tool exposes a 'Create Worktree from Branch' menu action and a worktree list panel. See our individual IDE guides for current state.

9. Mid-2024 · —

   AI agents adopt worktrees

   Claude Code ships the --worktree flag in mid-2024. Within twelve months, Codex, Cursor, OpenCode, and other AI editors converge on worktree-per-session as the default isolation pattern. Read the why in our Boris Cherny talk recap.

10. 2025–2026 · Git 2.46+

    Quiet maturity

    No headline changes to worktree itself, but the surrounding ecosystem (sparse-checkout, partial clone, scalar) now plays well with worktrees. Worktrees are no longer the new feature — they are the default expectation in modern Git workflows.

How to Check Your Version

Any Git from the last decade has worktree. To confirm yours does:

$ git --version
git version 2.45.2

$ git worktree --help

If git worktree --help opens a manpage, you are good. If it errors out, you are on something older than Git 2.5 (extremely rare in 2026 — even ancient Linux distros and macOS shipped 2.5+ within a year of its release).

The Subcommands You Actually Have

Every modern Git ships the full set:

• git worktree add — create a new worktree (Git 2.5+)
• git worktree list — show all worktrees (Git 2.5+, with --porcelain since 2.7)
• git worktree prune — clean up stale entries (Git 2.5+)
• git worktree lock and unlock — protect from pruning (Git 2.13+)
• git worktree move and remove — lifecycle commands (Git 2.14+)
• git worktree repair — fix broken cross-references (Git 2.23+)

The full official reference is at git-scm.com/docs/git-worktree, and Pro Git's second edition mentions worktrees throughout the advanced chapters.

What Did NOT Make It In

A few things people sometimes expect worktree to do but it does not:

• Shared working-tree state. Worktrees are independent checkouts. You cannot view two branches in one directory at once — that would require something like virtual branches (see GitButler).
• Branch sharing across worktrees. Each branch can only be checked out in one worktree at a time. Attempting to check out the same branch elsewhere produces the “already checked out” error.
• Remote worktrees. Worktrees are local. The remote sees only branches — read Does GitHub know you're using a worktree for what travels over the wire.

Where to Go Next

Now that you know worktree is part of Git itself, the practical starting points:

• Read what is git worktree if you want the concept explained
• Jump to git worktree add to create your first one
• Keep the cheat sheet open for the first month
• Set up your IDE so worktree shows up in your sidebar