Git Worktree: The Complete Guide

git worktree lets you check out multiple branches of the same repository into separate directories at the same time. Instead of stashing changes, cloning the repo, or constantly switching branches, you create lightweight linked working trees that share a single .git directory. This means you can review a pull request in one worktree, fix a hotfix in another, and keep your feature branch untouched — all without losing context.

This site is a comprehensive, community-driven reference for everything related to git worktree — from basic commands to advanced workflows with AI coding agents and IDE integrations.

Quick Start: Your First Worktree

Creating a new worktree takes a single command. From any existing repository, run:

Basic git worktree commands

# Create a worktree for an existing branch
git worktree add ../hotfix-login hotfix/login

# Create a worktree with a new branch
git worktree add -b feature/search ../search-feature main

# List all active worktrees
git worktree list

Each worktree is a full working directory backed by the same repository. Changes committed in any worktree are immediately visible to all others. When you are done, clean up with git worktree remove.

Tutorial

Step-by-step guides for every git worktree subcommand, from creating your first worktree to advanced management.

git worktree add

Create new worktrees from branches, commits, or tags

git worktree remove

Safely delete worktrees and clean up references

git worktree list

View all active worktrees and their checked-out branches

git worktree prune

Remove stale worktree entries after manual deletion

Merging Across Worktrees

Strategies for merging branches between worktrees

git worktree move

Relocate a worktree to a different directory path

Switching Worktrees

Navigate between worktrees and switch branches safely

Worktree Checkout

Understand how checkout interacts with worktrees

git worktree lock

Prevent a worktree from being pruned on shared drives

Guides & Best Practices

Production-tested patterns and workflows for using git worktree effectively in real projects.

Best Practices

Naming conventions, directory layout, and team workflows

Cheat Sheet

All git worktree commands on a single printable page

Workflow Patterns

Review-while-coding, parallel testing, and CI patterns

Bare Repository Setup

Use a bare repo as the base for all your worktrees

Submodules

How git worktree interacts with submodules

Node Modules

Handling node_modules and package managers across worktrees

Gitignore

Per-worktree ignore rules and exclude patterns

Git Hooks

Sharing and isolating hooks across multiple worktrees

Git Flow Integration

Using worktrees with the git-flow branching model

Large Repositories

Optimizing worktrees in monorepos and large codebases

Comparisons

Understand when to use git worktree versus other Git workflows, with side-by-side breakdowns.

Worktree vs Branch

When a separate worktree beats a simple branch switch

Worktree vs Clone

Worktrees share object storage; clones duplicate it

Worktree vs Stash

Avoid the stash-pop dance with persistent worktrees

skip-worktree vs assume-unchanged

Two similar flags with very different purposes

AI Coding Tools & Worktrees

Git worktree is the foundation for running multiple AI coding agents in parallel. Learn how to pair worktrees with the latest AI development tools.

Claude Code

Run parallel Claude Code sessions across worktrees

Cursor

Open multiple Cursor windows on different worktrees

OpenAI Codex

Use Codex CLI with isolated worktree environments

OpenCode

Worktree workflows for the OpenCode terminal agent

GitHub Copilot

Copilot context handling across multiple worktrees

Parallel AI Agents

Architecture for running many agents on one repo simultaneously

IDE & Editor Integration

How to use git worktree in your editor of choice, with setup guides and recommended extensions.

VS Code

Multi-root workspaces and worktree extensions

IntelliJ / JetBrains

Built-in worktree support in JetBrains IDEs

Neovim

Telescope, fugitive, and worktree.nvim plugins

Lazygit

Terminal UI for managing worktrees visually

GitKraken

Worktree management in GitKraken's GUI

Xcode

Using worktrees with Xcode projects and workspaces

GitHub Desktop

Workarounds for GitHub Desktop's worktree support

Sourcetree

Adding worktrees to Sourcetree's repository list

Zed

Worktree workflows in the Zed editor

Troubleshooting

Solutions to the most common git worktree errors and edge cases, with copy-paste fixes.

"must be run in a work tree"

Fix this error when running git commands outside a worktree

Cannot Delete Branch

Resolve locked branches that are checked out in another worktree

"not a git repository"

Broken worktree links and how to repair them

Invalid Reference

Handle missing branches and detached HEAD states

"already checked out"

Why Git prevents the same branch in two worktrees

Dirty Worktree

Safely remove worktrees with uncommitted changes

Why Use Git Worktree?

Zero-cost context switching

Each worktree is a fully independent working directory. Switch tasks by changing directories, not branches. Your build cache, open files, and IDE state remain exactly where you left them.

Disk-efficient parallelism

Unlike cloning, worktrees share the same Git object store. A second worktree adds only the working directory files — not another copy of your entire history.

Built for code review

Check out a pull request in a separate worktree, run tests, and review the code without touching your current work. Merge or close the PR, remove the worktree, and carry on.

AI agent isolation

Run multiple AI coding agents (Claude Code, Codex, Cursor) on the same repository in parallel, each in its own worktree, without merge conflicts or file contention.

Additional Resources

What is Git Worktree?Frequently Asked Questions Git Worktree Cheat Sheet