# Git Worktree `git worktree` is a built-in [[Git]] feature that lets a single repository check out **multiple branches into multiple working directories at the same time**. Instead of cloning the repo twice, you keep one `.git/` and attach extra working trees to it ; each tree on its own branch, sharing all objects, config, and remotes with the primary. It has been in Git since 2.5 (2015) but stayed niche for years. The recent surge of interest comes from AI coding agents: when N agents need to work on the same codebase in parallel without stepping on each other, worktrees are the cleanest isolation boundary that doesn't require cloning. ## The Core Commands ```bash # Add a worktree for a new branch off main git worktree add ../feature-x -b feature-x # Add a worktree for an existing branch git worktree add ../hotfix hotfix-1.2 # List all worktrees git worktree list # Remove a worktree (after merging or abandoning) git worktree remove ../feature-x # Prune metadata for worktrees deleted from disk git worktree prune ``` A worktree is a real directory with all files materialized; you can `cd` into it and use any Git workflow. The only constraint: you cannot have the **same branch checked out in two worktrees** simultaneously. ## Use Cases ### Classic developer workflows - **Long-running feature + urgent hotfix**: keep a `worktree main + worktree hotfix` instead of stashing - **Compare two versions side by side**: open two editors, two terminals, two trees - **Run a test suite on one branch while editing another**: no `git checkout` ping-pong - **Bisecting**: dedicated worktree for `git bisect run` so it doesn't disturb your active branch ### AI agent workflows This is the recent driver. Worktrees give every parallel agent its own filesystem without cloning: - **[[Cook (Orchestration CLI)]]** runs each parallel agent (race / vN / pick) in an isolated worktree on its own branch ; safe parallel `npm install`, safe simultaneous `pnpm test`, no contamination - **[[OpenClaw Sub-Agents]] doing multi-agent fan-out** can each get a worktree - **[[Claude Code Agent Teams]] / orchestration patterns** map cleanly onto "one agent = one worktree" The blast-radius story is the same as containers but lighter: agents can edit, run tests, even break their working tree, and the only damage is to one branch in one directory. ## Why Not Just Clone? You *could* clone the repo N times. Worktrees beat that on: - **Disk space**: objects, packfiles, LFS blobs are shared; only files-on-disk multiply - **Fetch cost**: one `git fetch` updates remotes for every worktree - **Hooks and config**: same `.git/hooks/`, same `.git/config`, same Git LFS state - **Sub-second add/remove**: no network, no full repack ## Common Gotchas - **Locked branches**: trying to check out the same branch twice fails by design ; use `git worktree add --detach` for a read-only ad-hoc tree - **Editor / IDE confusion**: VS Code and JetBrains tools treat each worktree as its own folder ; that's usually what you want, but settings/extensions don't auto-share - **Submodules**: each worktree gets its own submodule checkout; not free in disk - **`.gitignore`d build artefacts**: `node_modules`, `target`, `.next` etc. are *not* shared. Run `npm install` per worktree (or use a content-addressed store like pnpm's) - **Cleaning up**: deleting the directory without `git worktree remove` leaves orphan metadata; `git worktree prune` cleans it ## References - Documentation: https://git-scm.com/docs/git-worktree - Pro Git book: https://git-scm.com/book/en/v2/Git-Tools-Managing-Multiple-Worktrees ## Related - [[Git]] - [[GitHub]] - [[Cook (Orchestration CLI)]] - [[OpenClaw Sub-Agents]] - [[Claude Code Agent Teams]] - [[Crabbox]] - [[Scion]] - [[Superset]]