Understanding Git Worktrees

If you've been using Git for a while, you've probably been in this situation: you're deep into working on a feature branch, and suddenly you need to switch to another branch to fix a bug or review a PR. The usual approach is to either git stash your work or commit half-done changes before switching. Both of these are annoying and error-prone. What if I told you there's a better way?

Enter git worktree - one of the most underrated features of Git.

What is a Git Worktree?

A worktree lets you check out multiple branches of the same repository simultaneously, each in its own directory. Your main working directory stays untouched while you work on something else in a completely separate folder.

Think of it this way: instead of one repository with one checked-out branch, you can have one repository with multiple checked-out branches, each living in its own directory on your filesystem.

The key insight here is that all these worktrees share the same .git directory. So there's no duplication of your repository history. It's lightweight and fast.

Why Should You Care?

Here are some real situations where worktrees come in handy:

• Urgent hotfix: You're in the middle of a feature and need to fix a production bug. No need to stash or commit incomplete work. Just create a worktree, fix the bug, push it, and go back to your feature.
• Code reviews: You want to test a colleague's PR locally while keeping your own work intact.
• Running tests on another branch: You want to run the test suite on main while continuing to code on your feature branch.
• Comparing implementations: You want two different branches open side-by-side in separate editor windows.

Creating a Worktree

The basic syntax is straightforward:

git worktree add <path> <branch>

For example, if you want to check out the main branch into a directory called ../hotfix:

git worktree add ../hotfix main

This creates a new directory ../hotfix with the main branch checked out. You can cd into it and work there as if it were a regular Git checkout.

You can also create a new branch while creating a worktree:

git worktree add -b bugfix-123 ../bugfix-123

This creates a new branch bugfix-123 and checks it out in the ../bugfix-123 directory.

Listing Worktrees

To see all your active worktrees:

git worktree list

Output looks something like:

/home/user/project         abc1234 [feature-x]
/home/user/hotfix          def5678 [main]
/home/user/bugfix-123      789abcd [bugfix-123]

The first entry is always your main working directory.

Removing a Worktree

Once you're done with a worktree, clean it up:

# First, delete the directory
rm -rf ../hotfix

# Then, prune the worktree metadata
git worktree prune

Or, if the worktree is clean (no uncommitted changes), you can do it in one step:

git worktree remove ../hotfix

A Practical Workflow

Let me walk you through a real-world scenario. Say you're working on a feature branch and your team reports a critical bug in production.

Step 1: Create a worktree for the hotfix

# You're currently on feature-x branch in /home/user/project
git worktree add ../hotfix main

Step 2: Fix the bug in the new worktree

cd ../hotfix
git checkout -b hotfix/critical-bug
# make your fix
git add .
git commit -m "fix: resolve critical production bug"
git push origin hotfix/critical-bug

Step 3: Go back to your feature work

cd ../project
# Your feature-x branch is exactly where you left it
# No stashing, no half-baked commits

Step 4: Clean up after the hotfix is merged

git worktree remove ../hotfix

That's it. Your feature work was never interrupted. No stash conflicts, no "WIP" commits cluttering your history.

Things to Keep in Mind

You Can't Check Out the Same Branch Twice

Git won't let you have the same branch checked out in two worktrees simultaneously. If main is already checked out in one worktree, you can't check it out in another. This is a safety measure to prevent conflicting changes.

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

Worktrees Share the Same Refs

Since all worktrees share the same .git directory, operations like git fetch in one worktree will be visible in all others. Branches, tags, and remote tracking refs are shared.

Watch Out for Locks

If a worktree is on a removable drive or network mount that becomes unavailable, Git might think it's still in use. You can use git worktree lock and git worktree unlock to manage this.

# Lock a worktree (prevents pruning)
git worktree lock ../hotfix --reason "On external drive"

# Unlock when it's back
git worktree unlock ../hotfix

Keep Your Worktrees Outside the Main Repo

It's a good practice to create worktrees as sibling directories rather than inside your main repository. This avoids confusion with nested Git directories and keeps things clean.

parent-dir/
  project/          # main worktree (feature-x)
  hotfix/           # worktree for hotfix (main)
  bugfix-123/       # worktree for bug fix

Worktrees vs. Stash vs. Multiple Clones

You might wonder why not just use git stash or clone the repo again. Here's a quick comparison:

Worktrees hit the sweet spot between isolation and efficiency. You get separate working directories without the overhead of multiple clones.

Summary

git worktree is one of those Git features that once you start using, you wonder how you lived without it. It solves the common pain of context-switching between branches without the mess of stashing or committing incomplete work.

The next time you need to jump between branches, give git worktree a try. Your future self will thank you.

If you've any questions about Git worktrees, please let us know in the comments section below.