Exploring the Benefits of Git Worktree

As a developer, frequently switching between branches in Git can be a hassle. Whether switching between feature branches, fixing bugs, or reviewing code for a colleague, managing in-progress changes can become cumbersome. While stashing or committing these changes is an option, it can be inconvenient, especially if the changes are partially staged. In the past, I’ve resorted to cloning repositories multiple times to keep my development work separate from other branches. This was my workflow — until I discovered Git Worktree.

What is Git Worktree

In Git, the working tree, or worktree, is all files and subdirectories on the filesystem (outside of the .git directory) associated with the repository. Since version 2.5, Git has supported multiple working trees in a repository. These working trees are managed by the git worktree command. Multiple working trees allow for multiple branches to be checked out at a time.

Creating a new working tree looks similar to cloning the repository to a separate directory. But creating a new working tree is much lighter weight. The .git directory containing the repository’s history is shared between the working trees. This means the history of the repository isn’t duplicated, so only a copy of all the files in the current branch is checked out. This can make a big difference for a large repository: any additional working trees will take up much less space than a full clone of the repository. Additionally, any branches or stashes are shared between the working trees.

Adding a New Worktree

A new worktree can be added with the git worktree add <path>. This will create a new worktree at the path specified by <path>. By default, this worktree will create a new branch whose name is the final path component of <path>.

For example, running git worktree add ../example-clone in a repository will create a folder example-clone in the parent directory containing a checkout of a new branch called example-clone. By default, a new branch will be created based off the currently checked out branch. But the branch to checkout can also be specified with git worktree add <path> <branch>.

$ cd example
$ git worktree add ../example-clone
Preparing worktree (new branch 'example-clone')
HEAD is now at 8219f6a Initial commit

Listing Worktrees

The list of working trees in a repository can be shown by running git worktree list. This will list the main worktree (the original repository clone) first, followed by any linked worktrees (worktrees added to the main worktree).

To switch between worktrees, just change directories as you would with a normal folder or open a worktree’s folder in your editor of choice.

$ git worktree list
/Users/matt/example        8219f6a [main]
/Users/matt/example-clone  8219f6a [example-clone]

Removing a Worktree

A working tree can be removed by running git worktree remove <path>. The working tree must be clean with no modifications to tracked files for it to be removed. This can be overridden by adding the -force argument to the command, but verify that Git isn’t going to delete any desired changes as this isn’t reversible. Additionally, the main worktree (the original clone of the repository) cannot be removed.

$ git worktree remove ../example-clone
$ git worktree list
/Users/matt/example  8219f6a [main]

Worktree Advantages

It can be useful to have two (or more!) worktrees within your repository checkout.

For example, I like to have one working tree that I use primary for my development. I will usually use another working tree to run the changes from a pull request that I’m reviewing. This means I don’t have to stash or commit any current changes or switch branches when reviewing changes from another branch. I can checkout that branch in a separate working tree and the changes from my development working tree are left as they were when I return.

Multiple working trees also allow for opening up two editors containing two separate branches. This can be useful for comparing changes across branches, running branches in tandem, or working on a feature and bug fix at the same time.

When creating a pull request for a change, I’ll often include a screenshot or video comparing the behavior before and after the change. This could be done by running the changes from a development branch in one working tree and then using a separate working tree of the base branch to capture the original behavior.

Summary

Git worktrees are a powerful feature of Git which can enhance your development workflows. The ability to checkout multiple branches at a time reduces the friction of switching branches while having changes in progress and makes it easier to compare changes across branches. The next time you’re stashing or committing changes to switch branches, consider whether it makes sense to create a new worktree!

• Matt Czech

  Software Engineer

  More from Matt