Parallel development without the headaches using Git worktree

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

Recently whilst tinkering with a particularly tricky project, I came across Git’s [worktree](https://git-scm.com/docs/git-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/
├── my-project/          # main worktree, branch `main`
│   └── .git/            # main git directory
├── my-project-feature/  # linked worktree, branch `feature/login-form`
└── 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 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
git worktree add ../my-project-feature feature-branch

# Or create a new branch and worktree in one go
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`
my-project-feature/      # worktree for `feature-branch`
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.

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

Initial layout;

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

Create a feature worktree;

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

New layout;

~/Herd/
├── shop/           # main worktree, branch `main`
│   └── .git/
└── 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.

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

Your layout becomes;

~/Herd/
├── shop/                 # main worktree, branch `main`
├── shop-checkout/        # feature worktree, `feature/checkout`
└── 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.

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;

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

2. Switch to your main worktree directory;

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

3. Merge the feature branch;

   git merge feature-branch

4. 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. 😉

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]
/Users/barrd/Herd/shop-checkout        0c8ba118 [feature/checkout]
/Users/barrd/Herd/shop-payment-hotfix  a16e4be2 [hotfix/payment-fail]

You can mentally map this to something like;

[main]                → /home/user/Herd/shop
[feature/checkout]    → /home/user/Herd/shop-checkout
[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 worktree.

Once you’re done with a worktree, it’s good practice to tidy up. To do so safely, after committing or stashing any changes;

git worktree remove ../my-project-feature

This only works on clean worktrees (no uncommitted changes or untracked files) unless you pass --force and it cannot remove the main worktree.

Remember
Removing a worktree only deletes the working directory, it does not delete the branch itself. Always check with git status in that worktree before removing to avoid losing uncommitted work.

If you’ve deleted a worktree directory manually, Git still keeps metadata for it under the main repositories worktrees directory. In that case, git worktree list will show entries marked as missing.

You can clean up those stale entries with;

git worktree prune

To only prune entries that have been unused for some time, you can add an expiry;

git worktree prune --expire 7.days.ago

Using --expire now removes all stale worktree metadata immediately, which can be handy in a local development environment where you frequently nuke old unneeded directories.

It’s been around since v2.5, which was ~10 years ago and I’d never used it… But it’s now transformed my workflow, especially when juggling parallel features and urgent hotfixes. It keeps all the elements compartmentalised, reduces context switching and means stashing has become a rare exception.

For simple, sequential work, traditional branching is still the way to go but if you ever find yourself wishing you could be in two places at once, give git worktree a try.

If you’ve any favourite workflow variations you take advantage of please get in touch and let me know.

Article Information

Category: Technical
Topic: #Tech-Stack

• Git’s Database Internals (github.blog)
• Git Worktree Docs (git-scm.com)

Dave is a Bristol based Scottish Expat who has 20+ years experience of web development. Loves playing guitar, reading books, watching Sci-Fi and tinkering with tech.

Read more about Dave