Worktrees

Ever been knee-deep in something when somebody asks you to look at their code? Normally you'd have to save your work, switch branches, look at their stuff, switch back, and then try to remember where the heck you were. Annoying.

Worktrees fix that. They let you keep multiple branches open at the same time, each one in its own folder. It's like having several copies of your project, only smarter about it.

The Problem Worktrees Solve#

Say you're building a big feature. You've changed a ton of files and you're right in the middle of something. Then your coworker pings you with "Hey, can you review my pull request?"

Without worktrees you're stuck picking between two bad options.

1. Stash everything - Tuck your work away temporarily, switch branches, review the code, switch back and restore your work. It's messy and REALLY easy to botch.

2. Clone the project again - Make a whole second copy of the project. That eats disk space and takes time.

How Worktrees Work#

Here's one way to picture it. Normally your project folder looks something like this.

my-project/
  .git/
  src/
  package.json
  ... (all your files)

With worktrees you can make extra folders that are linked to the same repository.

my-project/           (main branch)
  .git/
  src/
  ...
 
my-project-feature/   (feature branch - a worktree!)
  src/
  ...
 
my-project-review/    (review branch - another worktree!)
  src/
  ...

Each folder shows a different branch, but they're all part of the same Git project. Anything you commit in one worktree shows up in the shared history.

Creating a Worktree#

The basic command to make a worktree looks like this.

git worktree add ../folder-name branch-name

Let's break it down.

• git worktree add - The command that creates a worktree
• ../folder-name - Where to put the new folder (usually right next to your project)
• branch-name - Which branch to check out in that folder

Step 1. Create a Worktree for an Existing Branch#

Let's say you want to review a coworker's branch called feature/new-login. Their branch lives on GitHub, so grab the latest list of branches first, then make the worktree.

git fetch
git worktree add ../review-login feature/new-login

That makes a new folder called review-login next to your project, with their branch checked out.

Step 2. Open It in Your Editor#

Now open that folder in a new editor window. Boom, both branches open at the same time!

Step 3. Remove It When Done#

When you're done reviewing, remove the worktree.

git worktree remove ../review-login

The folder disappears, but the branch and all its commits are still safe in Git. Heads up, Git refuses to remove a worktree that still has uncommitted changes or untracked files in it (that's on purpose). Commit or toss that work first, or add --force if you really mean it.

Creating a Worktree with a New Branch#

You can also make a brand new branch at the same time you make the worktree.

git worktree add -b new-branch-name ../folder-name

The -b flag tells Git to create a new branch. Super handy when you want to start fresh work without laying a finger on what you're already doing.

When Worktrees Are Useful#

Here's where worktrees really earn their keep.

Reviewing Pull Requests#

Somebody asks you to review their code. Make a worktree for their branch, look it over, test it, and delete the worktree when you're done. Your own work never gets touched.

Comparing Branches#

Want to see how the old version of a file stacks up against your new one? Open both in separate editor windows. No flipping back and forth.

Running Two Versions#

Maybe you need the main branch running while you test your feature branch. With worktrees you can have both running at once (on different ports).

Quick Bug Fixes#

You're deep in feature work and a critical bug needs fixing on main. Make a worktree for main, fix the bug, push it, and remove the worktree. Your feature work never moved an inch.

This gets more important the faster you move. After I picked up Claude Code (having never touched it before), I had something like 30 repos going in under a month. At that kind of pace, having more than one branch open at a time stops being a nice-to-have.

Worktree Commands Reference#

Here's every worktree command you'll actually need.

git worktree list

Shows all your current worktrees. Handy for seeing what you've got open.

git worktree add ../folder-name branch-name

Creates a new worktree with an existing branch.

git worktree add -b new-branch ../folder-name

Creates a new worktree with a new branch.

git worktree remove ../folder-name

Removes a worktree (deletes the folder). It only works on a clean worktree unless you add --force.

git worktree prune

Cleans up leftover worktree info if you deleted a worktree folder by hand.

A Real Example#

Let's walk through a full scenario. You're working on a recipe website and adding a shopping list feature.

Step 1. You're Working on Your Feature#

You're on the feature/shopping-list branch, deep in the code. Files are changed everywhere. Life is good.

Step 2. Someone Needs a Review#

Your teammate messages you with "Can you review my dark mode PR? It's on feature/dark-mode."

Step 3. Create a Worktree#

Instead of stashing everything, you fetch their branch and make a worktree.

git fetch
git worktree add ../recipe-review feature/dark-mode

Now you've got a new folder with their branch in it.

Step 4. Review the Code#

Open recipe-review in a new editor window. Look through the changes. Run the tests. Leave your comments on GitHub.

Step 5. Clean Up#

When you're done, clean it up.

git worktree remove ../recipe-review

The folder's gone. Back to your shopping list feature like nothing ever happened!

Worktrees vs. Multiple Clones#

So why not just clone the project twice? Fair question... here's why worktrees win.

Worktrees are faster, use less space and stay in sync automatically.

TL;DR#

• Worktrees let you work on multiple branches at the same time
• Each worktree is a folder with a different branch checked out
• They all share the same Git history and remote connections
• They're great for reviewing code, comparing versions or quick fixes
• Use git worktree add to create one and git worktree remove to clean up
• Way better than cloning your project over and over

What's Next?#

So far we've worked with repositories you own or have access to. But what if you want to pitch in on somebody else's project? Next lesson we'll cover the fork workflow, which is how you contribute to projects you don't own...