Understanding Git Worktrees

Work on multiple branches simultaneously without the overhead of multiple clones. One repo, infinite possibilities.

See the Difference Try the Simulator

Clone vs Worktree

See the dramatic difference in disk usage and workflow between multiple clones and worktrees

Multiple Clones

Traditional approach

Commit Propagation

git fetch required

Requires fetch to see new commits from other clones

Git Worktrees

Efficient approach

Instant Commit Visibility

Commits are instantly visible across worktrees

60% Less Disk Space

Worktrees share the same Git objects, meaning you only store the repository data once. Plus, commits are instantly visible across all worktrees!

Interactive Simulator

Click the command buttons to see how git worktree commands affect your file system in real-time

File System

/home/user/

>my-project

>.git

>HEADref: refs/heads/main

>config

objects

refs

>src

>index.ts

>app.ts

>package.json

>README.md

Green highlight = newly created | Orange text = .git file (not directory)

Terminal

Welcome to the Git Worktree Simulator!

Click a command button below to see it in action.

Click a command to execute:

Active Worktrees (1)

mainmain

/home/user/my-project

Mental Model

Understand the architecture: one .git directory, multiple working directories

Main Repository

my-project/

.git/

objects/- shared blobs, trees, commits

refs/- shared branches, tags

worktrees/- per-worktree data

HEAD- main worktree HEAD

index- main worktree staging

../my-project-feature

.git(file, not dir)

gitdir: ../my-project/.git/worktrees/feature

Own HEAD|Own index

../my-project-hotfix

.git(file, not dir)

gitdir: ../my-project/.git/worktrees/hotfix

Own HEAD|Own index

../my-project-experiment

.git(file, not dir)

gitdir: ../my-project/.git/worktrees/experiment

Own HEAD|Own index

Shared Objects

All commits, blobs, and trees are stored once in the main .git/objects directory. Worktrees reference them through symlinks.

Separate HEAD & Index

Each worktree has its own HEAD (current branch) and index (staging area), allowing independent work on different branches.

.git File Pointer

Worktrees have a .git file (not directory) that points back to the main repository's.git/worktrees/ directory.

What's inside the .git file in a worktree?

# cat my-project-feature/.git

gitdir: /home/user/my-project/.git/worktrees/feature

This single line tells Git where to find the actual repository data. The worktree-specific data (HEAD, index) lives in .git/worktrees/feature/ while shared data (objects, refs) remains in the main .git/ directory.

Quick Reference

Essential commands at your fingertips. Click the copy button to grab any command.

Pro Tips

Keep worktrees as siblings

Place worktrees next to your main repo, not inside it. This keeps things organized and avoids confusion.

Use descriptive paths

Name your worktree directories after their branches: ../my-project-feature-auth for the feature-auth branch.

Clean up regularly

Run 'git worktree prune' periodically to clean up references to deleted worktree directories.

No duplicate branches

You cannot have two worktrees on the same branch. This prevents conflicting work.

Common Workflow

git worktree add -b feature-auth ../feature-auth

Create new worktree with new branch

cd ../feature-auth

Navigate to the worktree

# ... do your work, commit, push ...

Work as usual, all git commands work

cd ../my-project && git worktree remove ../feature-auth

Clean up when done