Please Use Git Worktree

Please Use git-worktree

I often find myself in conversations with software developers who are unaware of git worktree. This powerful tool is a game-changer for managing multiple branches in a Git repository.

Have you ever been in the middle of working on a branch when you suddenly needed to switch to another one, only to realize you have a bunch of staged and edited files? The usual process involves stashing your changes, switching branches to complete the necessary tasks, and then returning to your original branch. But then you realize you forgot to “stash pop” your previous changes, and when you do, you’re hit with conflicts. To make matters worse, your build environment, like a Python virtualenv, might not be in sync with the new branch, leading to further issues. What a nightmare, right?

Enter git worktree.

Introduced in 2015, git worktree allows you to manage multiple working directories from a single repository, each one on a different branch. This approach prevents the common issues that arise when you try to switch branches with uncommitted changes. Unlike creating multiple clones of a repository, which can lead to conflicts if the same branch is checked out in different clones, git worktree ensures that each branch is safely isolated.

How I Use git-worktree

In my own workflow, I find git worktree incredibly useful. Here’s how I typically set it up:

First, I create a directory for my project, let’s call it myproject. Within this directory, I clone the repository’s main branch into a subdirectory named main. This working copy is dedicated to the main branch, and I avoid switching branches here, except for small bug fixes.

mkdir myproject
cd myproject
git clone http://git.example.com/myproject.git main
cd main

When I need to work on a new feature, I create a separate worktree for the feature branch. The -b option lets me create and check out a new branch in one step:

git worktree add -b my-feature-branch ../my-feature-branch

If I need to apply a hotfix to an existing release, I create another worktree for that specific branch. This time, I pass the existing branch name as the final argument:

git worktree add ../release-2024-09-03 release-2024-09-03

This setup gives me a clear, organized structure where each branch has its own dedicated working directory. My entire worktree list might look something like this:

$ git worktree list
/home/thomas/git/myproject/main                7330e84 [master]
/home/thomas/git/myproject/my-feature-branch   7330e84 [my-feature-branch]
/home/thomas/git/myproject/release-2024-09-03  7330e84 [release-2024-09-03]

With this setup, I can easily navigate to the specific branch I need by simply changing directories (cd) into the appropriate worktree. This approach not only keeps my environment clean and organized but also avoids the headaches that come with constantly switching branches in a single working directory.

In short, git worktree makes working with multiple branches seamless and conflict-free. If you haven’t started using it yet, give it a try—your workflow will thank you!