Git Worktrees

Source: Git Documentation | Type: Open Source (built-in Git) | Category: devops / version-control

What It Does

Git Worktrees is a built-in Git feature (available since Git 2.5, released 2015) that allows multiple branches to be checked out in separate directories on disk simultaneously, all sharing the same repository history and object store. Unlike cloning the repository multiple times, worktrees share .git objects, reducing disk duplication. Each worktree has its own HEAD, index (staging area), and working directory — so changes in one do not affect another.

The feature has found a new and prominent use case in AI-assisted development: running multiple AI coding agents (Claude Code instances, Cursor sessions, etc.) in parallel without file conflicts. Each agent operates in its own isolated worktree on its own branch, enabling what practitioners describe as “3x throughput” on tasks that can be parallelized across independent file sets. Claude Code has added native worktree support via the --worktree/-w flag and the ExitWorktree tool.

Key Features

• Multi-branch checkout: Check out multiple branches simultaneously in separate directories from one repository — no cloning required
• Shared object store: All worktrees share .git object storage; only working directory files are duplicated, not history
• Independent HEAD and index: Each worktree has its own staging area, so git add and git commit in one do not affect another
• Branch lock protection: Git prevents the same branch from being checked out in two worktrees simultaneously, avoiding corruption
• Standard Git commands: git worktree add <path> <branch>, git worktree list, git worktree remove — no plugins required
• Claude Code native integration: claude --worktree <name> creates an isolated worktree and starts a Claude Code session in it; ExitWorktree tool returns control
• Parallel agent isolation: Guarantees file-level isolation between concurrent AI agents — eliminates race conditions on shared files
• Merge-based reconciliation: Each worktree produces a standard branch that is integrated via normal git merge/rebase/PR workflows

Use Cases

• Use case 1: Parallel AI agent development — assign each Claude Code (or other AI agent) instance its own worktree branch; agents work simultaneously without file conflicts; merge results when done
• Use case 2: Hotfix while feature branch is in progress — work on a production hotfix in a separate worktree without stashing or interrupting the feature branch
• Use case 3: Parallel feature development — two engineers work on independent features simultaneously on the same machine without environment duplication overhead
• Use case 4: CI-like local validation — create a temporary worktree to run tests on a branch without disrupting your current working directory
• Use case 5: Ralph Wiggum loop parallelism — combine with the Ralph Wiggum pattern to run multiple autonomous overnight loops on independent tasks

Adoption Level Analysis

Small teams (<20 engineers): Fits for experienced Git users. The feature is built-in and free; the learning curve is moderate. Most useful when running parallel AI agent sessions. Disk space can become a concern — each worktree adds a full working directory copy (not object store, just files), which can consume several GB for large codebases.

Medium orgs (20–200 engineers): Fits well, especially for teams adopting AI-assisted development. Native Claude Code integration makes the setup low-friction. Teams should establish naming conventions and cleanup policies for worktrees (stale worktrees accumulate). Not all IDEs and GUI Git clients handle multiple worktrees gracefully — terminal/CLI workflows are more reliable.

Enterprise (200+ engineers): Fits for advanced users. The feature is mature and stable; no operational overhead beyond standard Git. However, at scale, the merge reconciliation step (integrating N parallel worktrees) becomes the throughput bottleneck. Teams report that beyond 5–10 parallel worktrees, merge coordination costs exceed the parallelism gains.

Alternatives

Evidence & Sources

• Official Git worktree documentation
• Claude Code common workflows — worktree section
• MindStudio: What Is the Claude Code Git Worktree Pattern?
• understandingdata.com: Git worktrees for parallel dev — 3x throughput claim
• Upsun DevCenter: Git worktrees for parallel AI coding agents
• devot.team: Git Worktrees — Boost Productivity with Parallel Branching

Notes & Caveats

• Disk space: Each worktree checks out a full working directory. A 2GB codebase with 5 worktrees consumes ~10GB on disk (working files only; objects are shared). Cursor forum users reported 9.82 GB consumed in a 20-minute session with a large codebase.
• Not process isolation: Worktrees isolate files but not processes. All agents on the same machine share environment variables, locally running databases, and network services. Agents that write to a shared database or cache will conflict even with worktrees.
• Self-inflicted merge conflicts: Running parallel agents on independent worktrees does not guarantee conflict-free merging if agents touch overlapping files. The safest assignment is strict file-set partitioning (one agent owns api/, another owns components/, etc.).
• IDE compatibility: Not all Git GUIs (Sourcetree, GitKraken) render multiple worktrees clearly. VS Code and JetBrains handle them adequately. Terminal-first workflows are most reliable.
• Stale worktree cleanup: git worktree prune removes references to deleted worktrees, but developers often forget this. Stale worktrees accumulate over time and can cause confusion.
• Branch lock collision: Git prevents checking out the same branch in two worktrees. If automation scripts do not name branches uniquely, they will fail with a lock error.
• Throughput ceiling: Practitioners report diminishing returns beyond 5–10 parallel worktrees. The bottleneck shifts from development to merge coordination. Beyond that threshold, sequential development may be faster.