Git Worktree

The git worktree command allows checking out multiple branches from the same repository into separate directories on the filesystem at the same time. Each directory is called a "worktree" and has its own independent working directory and staging area — but they all share the same Git history and objects.

Without worktrees, switching between branches requires stashing or committing current work before switching. With worktrees, two or more branches can be open simultaneously in separate folders.

Real-life analogy: Think of worktrees like having multiple physical desks in an office. Each desk has its own set of papers (branch files) that can be worked on independently. All desks share the same filing cabinet (repository history), but switching between tasks only means moving to a different desk — not clearing everything off the current one first.

Why Use Worktrees?

• Fix a production bug on main while continuing to develop a feature on another branch — without stashing or switching
• Run tests on one branch while making changes on another
• Compare two branches side-by-side in separate editor windows
• Work on a hotfix without interrupting current feature development

Creating a New Worktree

git worktree add <path> <branch>

Example — Open a Hotfix Branch in a Separate Folder

# Currently on: feature-dashboard (main worktree: ~/projects/my-app)
# Need to fix an urgent bug on main without leaving the feature branch

git worktree add ../my-app-hotfix main

This creates a new folder ../my-app-hotfix with the main branch checked out in it. Now two terminal windows can be open simultaneously:

• ~/projects/my-app — feature-dashboard branch
• ~/projects/my-app-hotfix — main branch

Create a Worktree with a New Branch

git worktree add -b hotfix-login ../my-app-hotfix main

Creates a new branch called hotfix-login starting from main and checks it out in the ../my-app-hotfix folder.

Listing All Worktrees

git worktree list

Output:

/home/ravi/projects/my-app          a3f92b1 [feature-dashboard]
/home/ravi/projects/my-app-hotfix   b7c3d45 [main]

Typical Worktree Workflow

# Main worktree: working on a feature
cd ~/projects/my-app     # [feature-dashboard branch]
# ... continue working on the dashboard ...

# Urgent bug report comes in!

# Create a hotfix worktree (in a new terminal)
git worktree add ../my-app-hotfix main

# Navigate to the hotfix worktree
cd ../my-app-hotfix      # [main branch]

# Fix the bug
echo "Fix applied" >> app.js
git add app.js
git commit -m "Fix critical login bug"
git push origin main

# Return to the feature work
cd ~/projects/my-app     # Still on [feature-dashboard] — untouched!

Removing a Worktree

When done with a worktree, remove it cleanly:

# First, navigate away from the worktree if currently inside it

# Option 1: Remove the worktree registration and delete its folder
git worktree remove ../my-app-hotfix

# Option 2: If files inside are untracked (force remove)
git worktree remove --force ../my-app-hotfix

If the folder was already manually deleted, clean up the stale reference:

git worktree prune

Important Rules and Limitations

• The same branch cannot be checked out in more than one worktree at the same time
• Each worktree has its own HEAD, index (staging area), and working directory
• All worktrees share the same .git folder and repository data
• Bare repositories (created with git init --bare) can also use worktrees and are sometimes used as the "main" worktree to avoid having a primary working directory

Worktrees vs Cloning

Practical Advanced Usage — Bare Repository with Worktrees

Some advanced developers use a bare repository as the central hub with multiple worktrees attached:

# Clone as bare (no working directory)
git clone --bare https://github.com/user/repo.git repo.git

# Add worktrees for different branches
cd repo.git
git worktree add ../repo-main main
git worktree add ../repo-develop develop
git worktree add ../repo-feature feature/new-ui

This gives clean separation between branches with maximum disk efficiency.

Summary

git worktree allows checking out multiple branches into separate folders simultaneously from a single repository. It eliminates the need to stash and switch when working on parallel tasks. Use git worktree add <path> <branch> to create a new worktree, git worktree list to see all active worktrees, and git worktree remove to clean them up. Worktrees are much more efficient than cloning the repository multiple times.