GIT WORKFLOWS / LESSON 02

Worktrees.

Working on multiple branches simultaneously

Written by Andrew Lee JenkinsPublished Oct 5, 202612 min readFree lesson

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.

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.
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.

Example

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

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

Example

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.

Example

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.

Example

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.

Example

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.

Example

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 from main. Create a fresh branch in another worktree with git worktree add -b hotfix/example ../hotfix main. Fix the bug there, push the branch, and remove the worktree when done. This works even when main is already checked out in your original folder.

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.

Example

git worktree list

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

Example

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

Creates a new worktree with an existing branch.

Example

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

Creates a new worktree with a new branch.

Example

git worktree remove ../folder-name

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

Example

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.

Example

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.

Example

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.

Feature	Worktrees	Multiple Clones
Disk space	One shared copy of the Git history, plus a checkout of your files per worktree	A full copy of the history AND the files every time
Git history	Always in sync	Can get out of sync
Setup time	Instant	Need to clone again
Remote config	Shared	Need to set up again

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...

Loading the lesson…

Loading activities…