Git Worktrees

Worktrees let you have multiple working directories attached to the same repository. Each worktree can check out a different branch simultaneously.

Why Worktrees?

Without worktrees, switching branches requires:

1. Stashing or committing current work
2. Switching branches
3. Doing urgent work
4. Switching back
5. Restoring your original work

With worktrees:

• Each branch has its own directory
• No stashing or context switching needed
• Work on multiple branches truly in parallel

When to Use Worktrees

Adding a Worktree

Basic Syntax

bash
1$ git worktree add <path> <branch>

Example: Create Hotfix Worktree

bash
1$ git worktree add ../project-hotfix hotfix/urgent-bug
2Preparing worktree (checking out 'hotfix/urgent-bug')
3HEAD is now at abc1234 Previous commit message

This creates:

• A new directory ../project-hotfix
• Checked out to hotfix/urgent-bug branch
• Shares the same .git data as your main worktree

Create Worktree with New Branch

bash
1$ git worktree add -b hotfix/new-fix ../project-hotfix main

This creates a new branch hotfix/new-fix from main in the new worktree.

Listing Worktrees

bash
1$ git worktree list
2/home/user/project              abc1234 [main]
3/home/user/project-hotfix       def5678 [hotfix/urgent-bug]

You can run this from any worktree to see all connected working directories.

Working in a Worktree

Each worktree is a full working directory:

bash
1$ cd ../project-hotfix
2$ ls
3README.md  src/  package.json  ...
4
5# Make changes
6$ vim src/bug.js
7$ git add src/bug.js
8$ git commit -m "fix: resolve urgent bug"
9$ git push origin hotfix/urgent-bug

Meanwhile, your original worktree remains untouched on its branch.

Removing a Worktree

When done with a worktree:

bash
1# Remove the worktree
2$ git worktree remove ../project-hotfix
3
4# Or if files were modified
5$ git worktree remove --force ../project-hotfix

If you manually deleted the directory, clean up the Git metadata:

bash
1$ git worktree prune

Worktree Constraints

One Branch Per Worktree

You cannot check out the same branch in multiple worktrees:

bash
1$ git worktree add ../another-main main
2fatal: 'main' is already checked out at '/home/user/project'

This prevents conflicting changes to the same branch.

Shared Git Directory

All worktrees share:

• Commit history
• Configuration
• Hooks
• Remote references

Each worktree has its own:

• Working directory
• Index (staging area)
• HEAD (current branch)

Advanced Usage

Worktree for Code Review

Temporarily check out a PR to review:

bash
1$ git fetch origin pull/123/head:pr-123
2$ git worktree add ../review-pr-123 pr-123
3$ cd ../review-pr-123
4# Review, test, run the code
5$ cd ../project
6$ git worktree remove ../review-pr-123

Worktree for Build

Run builds while continuing development:

bash
1$ git worktree add ../project-build release/v2.0
2$ cd ../project-build
3$ npm run build
4# Build runs in this directory while you work elsewhere

Commands Summary

Key Takeaway

Worktrees eliminate context-switching overhead for parallel work. Use them for hotfixes, reviews, builds, or any time you need multiple branches accessible simultaneously. Clean them up when done to avoid confusion.