Git Worktree
Simplifying Branch Management with Git Worktree
Introduction
Git worktree is a niche topic that I think doesn’t get enough attention. At first, the concept may seem a bit unnecessary, but once you find a great use case for it, it can be an immense improvement to your existing workflow. In this article, you’ll learn what a working tree is, some common commands, and the benefits of using worktrees.
Definition
The git worktree command allows you to manage and check out multiple “working trees” at the same time. A working tree in Git is essentially a directory that contains a checked-out version of your project files. When you clone a repository, Git sets up a working tree that holds the latest version of all files from that repository. As you make changes, these updates remain in your working tree until you choose to commit them.
Each working tree is linked to a specific branch in your repository, allowing you to work on different features or fixes simultaneously without interfering with each other. This means you can have separate environments for different branches, making it easier to manage multiple tasks at once.
TL;DR: The
git worktreecommand allows you to checkout multiple branches at the same time.
Use case: PR reviews
I started using worktrees when reviewing pull requests (PRs) for team members. Often, I am working on a feature branch, but I need to pause to review a team member's PR. The typical process is to stash any changes I have, check out the PR branch, review the changes, then switch back to my feature branch and apply or pop the stashed changes. This often delays my PR reviews because I don't want to disrupt my current workspace. However, since I started using worktrees, I can review PRs much faster by checking them out into a separate worktree that doesn't interfere with my ongoing work. This change has reduced disruptions to my workflow and allows me to work more efficiently as both a reviewer and an individual contributor.
Basic Commands
Now that you have a better idea of what a worktree is and why you might want to use it, let’s go over some common commands.
git worktree list
This command outputs the details of each worktree. The main worktree is listed first, followed by each of the linked worktrees.
git worktree add <path>/<branch-name> <remote-branch>
📌 Note: It is important to run this command from the root of the cloned repo.
For example, let’s say that you cloned this doggy-directory repo. After cloning, you would cd into the doggy-directory folder (or w/e you called it when you cloned it). Essentially, you are running the command in the main repo so that git knows what worktrees are available for you to add in the specified location.
Now if you were to run the command git worktree add ../worktrees/a11y-issues a11y-issues it would create a new worktree for the remote a11y-issues branch in the specified ../worktrees/a11y-issues directory allowing you to have a separate working environment for that branch.
git worktree remove <worktree-path>
As the name implies, this command is used to remove a worktree from the list of active worktrees. If Git encounters any issues while attempting to remove the worktree, you can use the --force flag to bypass these restrictions and ensure the worktree is forcibly removed.
git worktree prune
This command cleans up stale or orphaned worktrees that git still thinks exist but no longer do.
Realistic Workflows
Worktrees are useful, but most of the time, you need additional environment variables and configurations for your project to run properly. While simple projects might work with worktrees out of the box, even moderately complex setups typically demand further customization. Although I can't address every project setup scenario, I'll share an example of how I automated this process for my job's setup.
Automation with Git Worktrees
To give you some background, the main repository at my job is a full-stack app using the Laravel PHP framework for the backend and React with Inertia for the frontend. For local development, we use Herd, a native Laravel and PHP environment for macOS.
For a new worktree environment to work properly, it requires:
A copy of the
.envfile from the main repoUpdated environment variables based on the branch name
Frontend and backend dependencies installed
A new Herd site set up to serve the app locally
To avoid repeating these steps every time I review a pull request, I created two Bash scripts:
setup-worktree.shto create the new worktree and configure the project requirements.cleanup-worktree.shto remove the worktree when it's no longer needed.
Now, whenever I need to review a PR quickly, I just run ./setup-worktree.sh <feature-branch> and ./cleanup-worktree.sh <feature-branch> to set up and take down the worktree.
I won't share the full script here, but the main idea is: identify the steps you do repeatedly and automate them in a script because worktrees work well with some shell scripting.
El Fin 👋🏽
Git worktrees are a great way to manage multiple branches, making you more productive and smoothing out your workflow, especially when you're reviewing pull requests. By automating those repetitive setup tasks, you can make your development environment more streamlined and spend more time actually coding.
If you enjoy what you read, feel free to like this article or subscribe to my newsletter, where I write about programming and productivity tips.
As always, thank you for reading, and happy coding!
