Git Worktree

Canonical version: 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

# 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
• .gitignored 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

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

• 📚 KM for Beginners — 10+ hours of structured video lessons
• 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
• 💼 Knowledge Worker Kit — Complete guides + lifetime community
• 🦉 1-on-1 Coaching — Personalized guidance
• 🎯 Join Knowii — Community + ALL courses & tools