Parallel development without the headaches using Git worktree : barrd.dev

Skip to Content

Parallel development without the headaches using Git worktree

Created on

Jan 1st 2026<br>01/01/26

No updates

Approx ~10 minutes reading time for 1,916 words.

Introduction

Recently whilst tinkering with a particularly tricky project, I came across Git’s worktree feature. A tool that lets you work on multiple branches simultaneously, each in its own directory, all sharing the same underlying repository history.

Simple visualisation;

~/Herd/<br>├── my-project/ # main worktree, branch `main`<br>│ └── .git/ # main git directory<br>├── my-project-feature/ # linked worktree, branch `feature/login-form`<br>└── my-project-hotfix/ # linked worktree, branch `hotfix/payment-bug`

All the directories above share the same commit history and are linked to the same .git object database even though each has its own working directory state.

Each directory behaves like a normal checkout, you edit files, commit and push as usual, but you avoid constantly hopping branches in a single working tree.

Git Logo<br>Git version control logo shown as a branching diagram inside a tilted black square.

Traditionally, working on multiple branches meant a lot of git checkout and git stash constantly saving your place, switching context and hoping you didn’t lose anything important. It’s easy to get lost, especially when a production bug interrupts your flow. With git worktree you can add a new working directory for any branch (existing or new) and keep your workstreams separate. For example;

# Add an existing branch as a worktree<br>git worktree add ../my-project-feature feature-branch

# Or create a new branch and worktree in one go<br>git worktree add -b new-feature ../my-project-new-feature

This creates new directories at the same level as your main project, checked out to the branches you specify. You can now edit files, commit and push in each directory independently without touching your main working directory.

Here’s how your setup might look;

my-project/ # main worktree, branch `main`<br>my-project-feature/ # worktree for `feature-branch`<br>my-project-new-feature/ # worktree for `new-feature`

One important limitation is that the same branch cannot be checked out in more than one worktree at the same time. Each worktree must have a unique branch checked out. In practice, that encourages a tidy mapping of “one task, one branch, one directory”, which makes it easier to stay oriented mentally.

Practical example, juggling a feature and a hotfix

Here’s a realistic scenario, you’re working on a checkout feature when a production bug appears.

Initial layout;

~/Herd/<br>└── shop/ # main worktree, branch `main`<br>└── .git/

Create a feature worktree;

cd ~/Herd/shop<br>git worktree add -b feature/checkout ../shop-checkout

New layout;

~/Herd/<br>├── shop/ # main worktree, branch `main`<br>│ └── .git/<br>└── shop-checkout/ # linked worktree, branch `feature/checkout`

You can easily develop the checkout feature in shop-checkout while keeping shop on main for quick reviews.

A production bug appears, create a hotfix worktree

cd ~/Herd/shop<br>git worktree add -b hotfix/payment-fail ../shop-payment-hotfix

Your layout becomes;

~/Herd/<br>├── shop/ # main worktree, branch `main`<br>├── shop-checkout/ # feature worktree, `feature/checkout`<br>└── shop-payment-hotfix/ # hotfix worktree, `hotfix/payment-fail`

At this point you can;

Fix and test the production bug in the shop-payment-hotfix worktree.

Continue to iterate on feature/checkout in the shop-checkout worktree.

Keep shop free on main for merges and any code reviews.

How to merge a worktree into another branch

Merging changes from a worktree branch is just like any other Git merge, but the context is clearer because each branch lives in its own directory. Here’s a typical workflow for merging the feature branch into main;

Finish your work in the feature worktree and commit your changes.

Switch to your main worktree directory;

cd ../my-project && git checkout main

Merge the feature branch;

git merge feature-branch

Resolve any conflicts, then push.

Because each worktree is dedicated to a single branch, it’s much harder to accidentally commit to the wrong branch or lose your place when a hotfix interrupts your feature work… anyway, that’s the theory. 😉

Inspecting your current worktrees

Before you start removing or pruning anything, it helps to see what worktrees Git currently knows about;

git worktree list

Example output;

/Users/barrd/Herd/shop 66c16256 [main]<br>/Users/barrd/Herd/shop-checkout 0c8ba118 [feature/checkout]<br>/Users/barrd/Herd/shop-payment-hotfix a16e4be2 [hotfix/payment-fail]

You can mentally map this to something like;

[main] → /home/user/Herd/shop<br>[feature/checkout] → /home/user/Herd/shop-checkout<br>[hotfix/payment-fail] → /home/user/Herd/shop-payment-hotfix

It’s now obvious which branches are checked out and where thus helping to avoid trying to reuse a branch that is already attached to another...