index / a-simple-guide-to-git-worktrees

A simple guide to git worktrees

2026-09-01Frederik von Sperling #git

CONTENTS

01 — What are git worktrees?02 — A simple real-life example 03 — Cheat sheet

01What are git worktrees?#

Git worktrees are a feature that allows a developer to work on multiple working trees attached to the same repository. In practice, this means that you can have multiple folders containing the same repository, but with a different branch checked out.

Have you ever worked on a specific feature and suddenly had to attend to an urgent bug or maybe check out another feature as part of a pull request? Did you perhaps stash your changes or commit a broken state of your new feature, allowing you to checkout another branch?

Then worktrees are definitely something that you would find useful. Let us take a look at an example.

02A simple real-life example#

Lets say that you are working on a repository called repo. You have started to develop on a feature called feature-a. Therefore, you have created a branch from main named feature-a. While you are working your way through the feature, an urgent bug report is made. Instead of stashing your changes, you leave your feature-a for now and create a worktree.

Creating a worktree#

In order to create a worktree you need to define the location of the folder or working directory. While git can handle a worktree inside the primary repository, it is best practice not to do so, due to IDE tooling like file search, might be including files from both repositories. The command is:

terminalbash

git worktree add ../repo-bugfix-a

This would create a sibling folder to your current repository called repo-bugfix-a and would automatically track a new branch called repo-bugfix-a.

If you want to be explicit about the branch created, you can do it like so:

terminalbash

git worktree add ../repo-bugfix-a -b bugfix-a

Which now gives me a working directory named repo-bugfix-a tracking a branch called bugfix-a.

In order to track an existing remote branch, you just need to drop the -b parameter like so:

terminalbash

git worktree add ../repo-bugfix-a existing-bugfix-a

I like to prefix the name of the worktree folder with the name of the repository. This gives a better overview when working with multiple repositories.

Terminal showing the creation of a git worktree — Example of creation of a worktree with corresponding branch name

Cleaning up#

When the bug is fixed and committed, you can jump back to your main repository. In order to clean up the newly created worktree, you can simply run:

terminalbash

git worktree remove ../repo-bugfix-a

03Cheat sheet#

Add a worktree called feature-a tracking a branch called feature-a

$ git worktree add ../feature-a -b feature-a

Add a worktree called feature-a tracking an existing branch called feature-a

$ git worktree add ../feature-a feature-a

List all current worktrees

$ git worktree list

List detailed information of all current worktrees

$ git worktree list --verbose

Remove a worktree called feature-a

$ git worktree remove ../feature-a

If you want to learn more, please checkout the documentation at: https://git-scm.com/docs/git-worktree

QUESTIONS & ANSWERS

When to use git worktree?

If you find your self working on multiple features, having to fix a urgent bug while working on another feature or if you need to checkout a branch for PR during development, git worktree is a really useful feature

Is there any limitations or down sides to git worktrees?

A branch can only be checked out in one worktree at a time. Trying to check out the same branch in multiple worktrees will throw an error.

Any neat tricks to git worktrees not covered by official documentation?

You are able to apply a stash in one worktree that were created in another worktree.

← OLDERYou can now see the cost of your Claude Code session

Get an email when a new post is published. Nothing more.