While working in a feature development branch, an urgent alert pops up in Slack: "Production is throwing errors." You shelve unfinished changes with git stash, switch back to main with checkout, reinstall dependencies, rebuild, and finally begin investigating—when handling multiple projects and branches in custom development, you end up repeating this switch dozens of times a day. Every switch triggers re-installations of node_modules and rebuilds, while accidents like lost changes from forgotten stashes lurk around the corner. Switching tasks ends up costing more time than the actual work itself.
As the GitHub Blog highlighted in "What is git worktree and why should you use it?", this switching cost can be substantially reduced with git worktree. git worktree is a mechanism that lets you check out multiple working directories simultaneously from a single repository. In this article, we explore how worktree helps in parallel client development and where teams typically stumble during adoption, written from the perspective of an active development team.
Why switching branches with checkout is so painful
Switching branches with git checkout (or git switch) completely rewrites the contents of your working directory to match the target branch state. While this is expected Git behavior, its side effects in modern development are heavy.
First is recreating build artifacts and dependencies. If different branches have different package.json or lockfiles, dependencies must be reinstalled on every switch. Frontend build caches are invalidated, requiring development servers to be restarted.
Second is shelving in-progress changes. If you have uncommitted changes, you cannot simply check out another branch. You have to park them using stash, but as stashes accumulate, it becomes unclear which work belongs to what, creating a breeding ground for forgotten restores.
Third is mental context switching. Because the contents of the same directory morph into something else, files open in your editor switch context completely, making it time-consuming to recall what you were doing just moments before.
git worktree sidesteps all three issues at once. By maintaining separate directories per branch, directories for emergency hotfixes and feature development can coexist simultaneously, turning context switching into nothing more than switching folders.
git worktree fundamentals: One repository, multiple workspaces
Think of worktree as branching out another working directory from an existing repository. For instance, to open main in a separate directory for an emergency hotfix, you write:
# いまのリポジトリから ../project-hotfix に main を展開する
git worktree add ../project-hotfix main
# 新しいブランチを切りつつ別ディレクトリで開く
git worktree add ../project-feature-x -b feature/search-improveNow ../project-hotfix and ../project-feature-x exist as independent working directories. Because the underlying .git data is shared with the original repository, fetched history and remote configurations remain common across all directories. There is no need for stash, allowing you to jump straight into hotfix resolution without halting feature development.
Once finished, instead of deleting the directory manually, clean it up with worktree.
git worktree remove ../project-hotfix # 作業ディレクトリを除去
git worktree list # 今ある worktree を一覧As a caveat, you cannot check out the exact same branch in two worktrees simultaneously. This constraint prevents contradictory states; branches must be distinct across worktrees.
How it benefits parallel client projects
In custom development, it is routine for a single project to simultaneously have an active production branch, ongoing feature branches, and peer branches awaiting review. Separating these with worktree ensures individual workflows never interfere with one another.
| Typical scenario | Workflow without worktree | Workflow with worktree |
|---|---|---|
| Urgent bug fix arrives during feature development | stash → checkout → rebuild | Handle immediately in separate directory; main work stays intact |
| Locally reviewing a peer's PR | Shelve own changes and checkout | Simply open in review directory |
| Concurrent long-term branch and quick hotfixes | Reconstruct environment on every switch | Maintain environment within each directory |
This proves especially powerful when running long-running builds or test suites in a separate directory while continuing other work in the primary workspace. Downtime spent idling for CI to complete is minimized. It also pairs naturally with delegating branch tasks to AI coding agents; dedicating an isolated directory to an agent prevents your local work from being disrupted. Structuring development workflows with agents is particularly effective when combined with the principles covered in our article on development workflows using Claude Code.
Pitfalls encountered when rolling it out in client work
On an enterprise system project where our team stepped in to rebuild the development setup (keeping the company name confidential), every team member was alternating between feature work and production troubleshooting inside the exact same directory. This led to monthly accidents where someone stashed in-progress work during an emergency, only to face nasty conflicts when restoring it.
We transitioned the team to an operating model where each developer maintained two worktrees: one for feature development and one for production responses. Hotfixes were completed entirely within the production directory, leaving the local feature workspace untouched. This completely eliminated incidents caused by forgotten stashes.
The biggest hurdle in this transition was handling environment config files and build caches. Files outside Git tracking, such as .env, are not shared between worktrees and must be placed again whenever a new directory is created. We solved this by providing a setup script that copies required files upon worktree creation. Furthermore, because node_modules is maintained separately per worktree, disk usage increases. In storage-constrained environments, combining this with shared dependency stores (such as pnpm store) is necessary. Reviewing the overall architecture of repositories and dependencies alongside the insights in our article on eliminating dependency drift with monorepos allows parallel development and dependency management to be designed cohesively. Including constraints like being unable to check out the same branch twice, it is practical to recognize that worktree is not a silver bullet, but a tool that shines brightest in projects heavy on concurrent work.
Where to begin
The first step is simply noticing how many times a day you switch branches. If you find yourself repeatedly stashing and rebuilding for hotfixes or PR reviews, offloading that work into a secondary worktree will virtually eliminate context-switching overhead. Start by adding a single directory dedicated to hotfixes and automating .env copying to feel the benefits right away.
If context switching across parallel projects is slowing down development, urgent hotfixes are breaking in-progress work, or you want to streamline your team's development flow, reach out through GleamHub's contact form. We will assess your current development setup and assist with everything from establishing worktree workflows to optimizing CI and review operations.
