Demystifying Git Worktrees

The Cheatsheet

Create new worktree with new branch

Create a new worktree/branch in a sibling folder

git worktree add ../[path] -b [branch_name]

# creates a sibling folder named add-card-component with the feat/add-card-component branch
git worktree add ../add-card-component -b feat/add-card-component

Create new worktree from existing branch

Creates a new worktree using an existing branch

git worktree add ../[path] [branch_name]

# creates a sibling folder name "add-button-component" with the "feat/add-button-component" existing branch
git worktree add ../add-button-component feat/add-button-component

List existing worktrees

List existing worktrees

git worktree list

Remove worktree

Remove worktree once you’re done with it

git worktree remove ../[path]

# remove a sibling folder/worktree named "add-button-component"
git worktree remove ../add-button-component

What are Git Worktrees?

Git worktrees allow you to check out multiple branches from one cloned repository as folders in your filesystem. Each folder can be run as a completely separate copy but there’s the advantage of shared .git data across the trees. For example, if you do a git fetch origin in one worktree, origin is updated across all worktrees since they share data with the main repository.

Effectively, you end up with this structure:

|- main repository
|- sibling folder checked out with a branch
|- another sibling folder
|- another sibling folder

// eg.
|- my-react-app # can be checked out as anything like usual
|--- .git
|--- package.json
|--- etc.
|- add-button-component # checked out as add-button-component
|--- .git
|--- package.json
|--- etc.
|- add-card-component # checked out as add-card-component
|--- .git
|--- package.json
|--- etc.

Creating a worktree

When creating a brand new worktree, you need to know where to save it and what branch you want the worktree to be checked out as.

git worktree add ../[path] -b [branch_name]

# creates a sibling folder named add-card-component with the feat/add-card-component branch
git worktree add ../add-card-component -b feat/add-card-component

This new worktree is now fully separate from the main one except for git tracking.

If you want to use an existing branch, drop the -b flag and the same command works

git worktree add ../add-button-component feat/add-button-component

Working with worktrees

You can treat worktrees like separate repos and when you’re done, just clean it up:

git worktree remove ../add-button-component

If you’re like me and keep all of your projects in one folder, it might be hard to tell apart a worktree from a regular project. In that case, you can ask git for a list:

git worktree list

Workflow

The workflow for git worktrees is way simpler than one might expect. Here’s my usual flow when I’m working on a new bugfix:

go to my project, do a git pull on main
git add worktree ../bug-description-of-bug -b fix/description-of-bug
do my work and commit it
go back to main project folder
git remove worktree fix/description-of-bug