Mastering Git Worktree

Use Cases - why and when to use

1. Suppose you are working on a code base with multiple branches, sometimes there is a need when you wish you could checkout multiple branches. Why...? you may ask. Well, let's say you are working on some exciting and complex feature and all of a sudden there's a support issue that needs fix (Doesn't that happen, like... always :) ). Your team needs fix - immediately, and you are not ready to comit the code which is WIP, because there are some not-tested workflows, some in-progress code statements, pending refactoring and then some things.
2. Let's say, there's a test that you want to perform. Merging/Rebasing main branch on your branch, which is out-of-sync for a long time. If you are learning, like me, more often than not, it can break a lot of things before I see the result and I'd like to reset stuff and not loose the work I did over past few days. So, I need to work in isolation and proceed only if the results are to my satisfaction.
3. You need to review code in a different branch and again - you don't want to change anything in your current state of code.
4. You want to experiment 2 different approaches of a solution, but can only implement one at a time. What if you could implement 2 solutions in different places, without having to commit and switch branches?
5. You want to look at the state of code in it's entirety when that commit was made. So, basically you want to checkout a ref. e.g., You need to inspect a release version in production, identified by a specific tag or ref, for debugging.
6. And many more scenarios where your current state of code can't be touched for x, y, z reasons and you could really use a fresh copy of code to experiment with.

You can, of course, clone another repository of the same code base and for small repos this could work fine. However, you can do better. This is where?git worktree?comes to save the day and some space on your computer.

Git worktree is a powerful feature that allows developers to work on multiple branches simultaneously without switching between them. It creates separate working directories for different branches, enabling you to have multiple versions of your project checked out at once. Let's explore this feature through following examples of increasing complexity.

1. Your First Worktree

Let's say, you're working on the?feature-x?branch and want to create a new worktree for another?fix?.

# CWD is your main repository directory
git worktree add ../fix-branch fix-branch        

This command creates a new directory named?fix-branch?one level up from your current directory, checks out the?fix-branch?there. You can now work on both branches simultaneously in separate directories, without having to clone another copy of the repository.

2. Managing Multiple Worktrees

As your project grows, you might need to juggle multiple features or bug fixes. Here's how to manage several worktrees:

# Create worktrees for different features
git worktree add ../feat-a feat-a
git worktree add ../feat-b feat-b
git worktree add ../major-bugfix major-bugfix

# List all worktrees
git worktree list

# Remove a worktree when you're done
git worktree remove ../feat-a        

This example demonstrates creating multiple worktrees, listing them, and removing one when it's no longer needed.

3. Working with Detached HEAD

Why stop here. Often, you need to examine or work on a specific commit without creating a branch. Worktrees can help with this:

# Create a worktree for a specific commit
git worktree add --detach ../old-version randomcommit

# Make changes and create a new branch if needed
cd ../old-version
git switch -c new-hotfix

# Clean up when done
cd -
git worktree remove ../old-version        

Here, we create a worktree in a detached HEAD state, make required changes to it, and potentially create a new branch from an old commit.

4. Worktrees for CI/CD

Worktrees can be invaluable in CI/CD pipelines. In an Enterprise setup, you might want to create multiple "deployables" for different environments with their own configurations, such as - for customer-x, customer-y or geo-1, goe-2 and so on... Here's an example of how you might use worktrees to build and deploy different versions of your app:

#!/bin/bash

# Create worktrees for production and staging
git worktree add ../customer-x-build customer-x
git worktree add ../geo-y-build staging

# Build production version
cd ../customer-x-build
npm install
npm run build
# Deploy x build...

# Build staging version
cd ../geo-y-build
npm install
npm run build
# Deploy staging build...

# Clean up
cd -
git worktree remove ../customer-x-build
git worktree remove ../geo-y-build        

This example script creates separate worktrees for different configs, builds each version, and could be extended to deploy them to different environments.

### Tip

Use git worktree prune to remove references to worktrees that no longer exist on disk.

---

As we saw here, Git worktree is a powerful yet simple feature that can significantly improve the development workflows, especially when working on multiple features or maintaining different versions of your project. As you've seen through these examples, it can be used for simple branch management, complex CI/CD pipelines, and even automated development environments. What would you use the worktrees for? Comment and share with us.