Tutorials•Pillar Guide

Git Worktree: Complete Guide

A Git worktree enables you to attach multiple isolated working directories to a single Git repository. Work on multiple branches simultaneously without stash conflicts, branch switching overhead, or duplicate disk-heavy repository clones.

Simultaneous Branches

Checkout 3, 5, or 10 branches at the same time in separate folders on your machine.

Zero Disk Duplication

All linked worktrees share the primary .git history and object database.

Zero Stashing

Switch contexts instantly for PR reviews or emergency hotfixes without stashing uncommitted files.

What is a Git worktree?

In standard Git usage, one repository directory corresponds to exactly one working directory and one active checked-out branch. Switching branches modifies files directly inside that single directory, requiring you to commit or stash any uncommitted work.

With Git worktrees (introduced natively in Git 2.5 and refined in subsequent versions), a single repository can have multiple linked working directories. Each working directory is checked out to its own branch, but they all share the exact same commit history, object store (.git/objects), remotes, and configuration.

Architecture: Shared Object Database (.git) vs Isolated Working Directories

~/projects/my-appMain Worktreebranch: [main]Has actual .git folder

~/projects/feature-authLinked Worktree #1branch: [feature/auth].git is a pointer file

~/projects/hotfix-loginLinked Worktree #2branch: [hotfix/login].git is a pointer file

All linked worktrees share the same central Git storage

.git/objects (commits, trees, blobs) • .git/refs • .git/config

Zero duplicate history downloaded. Instant creation. Zero wasted disk space.

How Git worktrees work internally

Under the hood, Git organizes worktrees using a lightweight pointer architecture:

Primary Worktree: The original folder created when you initialize or clone a repository. It contains the real .git/ directory.
Linked Worktrees: Additional folders created via git worktree add. Instead of a .git directory, each linked worktree has a tiny .git text file containing a single line pointing back to the main repository: gitdir: /path/to/main/.git/worktrees/<worktree-name>.
Administrative Storage: The main repository keeps per-worktree state (HEAD pointer, index, worktree-specific config, logs) under .git/worktrees/<id>/.

Git worktree vs normal branch switching

Traditional branch switching interrupts your flow whenever an unexpected interruption occurs. Compare the two models below:

Traditional Workflow (git checkout / switch)

Single Folder

1. Working on feature-a

↓ Urgent bug reported!

2. git stash save or half-baked commit

↓

3. git switch main & wait for IDE re-index

↓

4. Fix bug, switch back, git stash pop

Git Worktree Workflow (Simultaneous)

Parallel Folders

1. Folder A: feature-a in Editor 1

↓ Urgent bug reported!

2. git worktree add ../hotfix main

↓

3. Folder B: Open in Editor 2, fix & commit

↓

4. Folder A is intact. Zero stashes, zero lost context!

Comparison Point	git switch / checkout	Git worktrees
Parallel Branches	1 branch at a time	Unlimited simultaneous branches
Uncommitted Changes	Requires stash or throwaway commit	Untouched; stay in their own folder
IDE / Language Server Cache	Re-indexes on every branch switch	Warm & intact in separate IDE windows
Dev Server / Port State	Must stop/restart on branch change	Can run concurrently on separate ports
Disk Space Usage	1 working tree	Only working tree files (shared .git)

Git worktree directory structure

A recommended layout is placing sibling folders side-by-side or inside a dedicated project root. This ensures relative imports and navigation remain intuitive:

Recommended Directory Hierarchy

projects/
├── my-app/                <-- Primary Worktree (contains full .git/ repository)
│   ├── .git/
│   │   └── worktrees/
│   │       ├── feature-auth/
│   │       └── hotfix-login/
│   └── src/
│
├── my-app-feature-auth/   <-- Linked Worktree 1 (checked out to feature/auth)
│   ├── .git               <-- Text file pointing to ../my-app/.git/worktrees/feature-auth
│   └── src/
│
└── my-app-hotfix-login/   <-- Linked Worktree 2 (checked out to hotfix/login)
    ├── .git               <-- Text file pointing to ../my-app/.git/worktrees/hotfix-login
    └── src/

Git worktree commands overview

Explore all 8 dedicated command tutorials with deep examples, flags, and diagrams:

git worktree add#1

Add Guide

Create a linked worktree from an existing branch, commit, or new branch.

Read tutorial

git worktree list#2

List Guide

View and inspect all linked worktree directories, HEAD commits, and active branches.

Read tutorial

git worktree remove#3

Remove Guide

Safely delete a worktree directory and unregister its administrative record.

Read tutorial

git worktree move#4

Move Guide

Relocate a linked worktree directory and automatically update internal Git pointers.

Read tutorial

git worktree lock#5

Lock Guide

Lock a worktree to prevent accidental removal or automatic pruning.

Read tutorial

git worktree unlock#6

Unlock Guide

Release the lock on a worktree so it can be moved, deleted, or pruned.

Read tutorial

git worktree prune#7

Prune Guide

Clean up stale administrative records whose worktree folders were deleted manually.

Read tutorial

git worktree repair#8

Repair Guide

Re-establish bi-directional links between the repository and moved worktrees.

Read tutorial

Real-world practical workflows

1. Parallel development without stash mess

When building a complex feature on feature/billing, you need to spin up feature/auth to test integration. Instead of stashing:

Terminal

# Create a new branch and folder directly from main

$git worktree add -b feature/auth ../app-auth main

Now open ../app-auth in a second VS Code / IntelliJ window. Both branches run independently.

2. Emergency production hotfix

A critical production bug is reported while you have 15 modified files in your current working tree. Do not risk losing state:

Terminal

# Branch directly from production tag or branch

$git worktree add -b hotfix/payment-gateway ../app-hotfix production

Fix the bug, test, commit, push, and create your PR. Then safely clean up with git worktree remove ../app-hotfix.

3. AI coding agents (Claude Code, Cursor, Codex, Antigravity, Qwen, Kimi, OpenCode)

Autonomous AI agents often perform aggressive refactors, install test packages, or modify configuration files. Running an AI agent in your primary working directory can overwrite your active work. By assigning each AI task its own worktree:

Terminal

# Isolate the AI agent in its own sandbox directory

$git worktree add ../agent-refactor -b ai/refactor-auth

Point your coding agent (such as Claude Code, Cursor, Codex, Antigravity, Qwen, Kimi, or OpenCode) at ../agent-refactor. You can continue writing code on your main branch without AI-generated file conflicts.

Common problems & restrictions

A branch cannot be checked out in two worktrees simultaneously

Git prevents you from checking out the exact same branch in two different worktrees to prevent index corruption. If you try, Git will report: fatal: 'branch-name' is already checked out at '/path/to/worktree'. Use git worktree list to find where it is currently checked out.

Uncommitted changes during deletion

Running git worktree remove will fail if the directory has untracked or uncommitted changes. This protects you from accidental data loss. Learn safe cleanup on the git worktree remove guide.

Managing Git worktrees with WorktreeWise GUI

While the Git CLI commands are powerful, visual tools eliminate path memorization, automate hooks, and manage IDE integration effortlessly:

WorktreeWise

Central Worktree Dashboard

Try Free

WorktreeWise provides an intuitive visual interface to inspect all linked worktrees, switch IDE windows, run custom pre/post creation hooks, and repair broken links in 1-click.