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

A simple guide to git worktrees

2026-09-01updated 2026-09-15Frederik 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 developers 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 developing 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 is discovered. 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 new working directory. While git can handle a worktree inside the main repository, it is best practice not to do so, due to IDE tooling, like file search, might show results 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 name of the branch created, you can do it like so:

terminalbash

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

Which now gives you 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

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 NEWER →The fear of AI fatigue proved to be unfounded

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