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

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/ ├── 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. The difference between Git branch and worktree Git Logo 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. 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/ └── 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. A production bug appears, create a hotfix worktree 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. 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] /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. How to remove a 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. Cleaning up stale worktrees with prune If you’ve deleted a worktree directory manually, Git still keeps metadata for it under the main repositories worktrees directory.