Using Git Worktree Deliberately for Local Code Reviews

1. The problem with branch switching for parallel reviews

A quick review in between usually means: stash your own changes with git stash, switch to the branch under review, look through the code, then switch back and reapply the stash. For a single, short interruption that is still manageable, but with several parallel reviews on the same day the overhead adds up noticeably.

More disruptive than the raw time cost is often the side effect on running processes: a dev server, a watcher for Tailwind CSS builds, or a running Docker container usually operate on whatever is currently checked out in the working directory. Switching branches mid-review throws these processes out of sync or requires a full restart once you switch back to your own branch.

2. What a git worktree is and how it differs from cloning

A git worktree is an additional working directory that shares the same internal .git data store as the original repository but provides its own, independent checkout of a specific branch on the filesystem. Objects, commits and configuration are not duplicated but shared, which means an extra worktree needs barely any additional disk space compared to a full second clone of the repository.

Unlike a full second clone, worktrees stay tightly connected: a new commit created in one worktree is immediately visible as a reference in the main repository and in every other worktree, with no need to push and fetch between the directories first.

3. Creating a review worktree for a pull request branch

The git worktree add command takes a target path and, optionally, a branch name, and sets up a full, independent checkout from it. If the given branch already exists locally, it gets checked out right there; if it only exists remotely, Git automatically checks it out as a new local tracking branch in the new directory.

For a review, a single command is therefore enough: a new directory appears next to the main repository, the branch under review is fully checked out there, and your own work in progress in the main directory stays completely untouched throughout, including any uncommitted changes and running background processes.

# Create a new worktree for an existing feature branch
git worktree add ../review-checkout-redesign feature/checkout-redesign

# Create a new worktree for a branch that only exists remotely
git worktree add ../review-pricing-fix origin/fix/pricing-rounding

4. Checking out existing remote branches directly into a worktree

For reviewing pull requests from GitHub or GitLab, the associated remote branch can be referenced directly when creating the worktree, without first fetching manually into the main repository and creating a local branch there. A single git fetch followed by git worktree add is usually enough to make a submitted branch fully available locally.

For projects using the GitHub or GitLab CLI, this step can be simplified further: gh pr checkout checks out a pull request branch directly, and combined with a prepared worktree directory, the actual review workflow still stays fully separated from your ongoing work.

# Fetch the current state of all remote branches, then create a worktree
git fetch origin
git worktree add ../review-pr-142 origin/feature/pr-142

5. Managing several worktrees: list, lock and remove

As the number of parallel reviews grows, a regular glance at git worktree list pays off, since it lists every currently existing worktree along with its path and checked-out branch in a clear overview. That makes it easier to keep track of which directory belongs to which review, especially when several pull requests are being checked at the same time.

For worktrees on external or occasionally disconnected drives, git worktree lock prevents Git from mistakenly treating that worktree as orphaned during internal cleanup and removing it automatically while the drive is temporarily disconnected. Once a review is finished, git worktree remove cleanly removes the directory again, including the corresponding internal reference in the main repository.

# List every currently existing worktree with its path and branch
git worktree list

# Cleanly remove a finished review worktree
git worktree remove ../review-pr-142

6. Combining worktrees with your IDE workflow

Since every worktree is its own directory on the filesystem, PhpStorm or a comparable IDE can open a separate project window for each review, entirely independent from the main project window holding your own work in progress. A review comment, jumping to a definition, or a test run started on a whim then always operates in the right context, without accidentally affecting your own branch.

For Magento or Hyvä projects with their own Docker setup, that additionally means a separate compose setup or a dedicated database container can be started specifically for the review worktree, while the familiar development environment in the main directory keeps running unaffected.

7. Cleanup: removing deleted worktrees and orphaned references

If a worktree directory gets deleted manually through the filesystem by accident instead of through git worktree remove, the main repository is left with an orphaned internal reference at first, which shows up flagged as broken the next time you list worktrees. git worktree prune cleans up exactly these orphaned references by checking which referenced directories still actually exist and removing every remaining stale entry automatically.

An occasional, regular git worktree prune is especially worthwhile with a high turnover of short-lived review worktrees, so the repository's internal bookkeeping does not needlessly accumulate references to directories that no longer exist.

# Remove orphaned references to manually deleted worktree directories
git worktree prune

8. Limitations and pitfalls of worktrees in everyday review work

The same branch cannot be checked out into two different worktrees at the same time, Git deliberately prevents that to avoid conflicting simultaneous changes to one and the same branch. For parallel reviews of different branches that is no issue at all, but it does matter if the same branch is accidentally opened twice.

In addition, every worktree of a repository shares the same underlying object database, which means aggressive, destructive operations such as git gc --aggressive or manually deleting objects in the main repository can in theory affect other worktrees too. In everyday review work built purely on reading and testing, this risk practically never comes up.

9. Comparison to stash-based context switching

The classic sequence of git stash, switching branches and later git stash pop remains a legitimate, simple option for very rare, one-off interruptions, especially when no second directory should be created at all. But once reviews happen regularly, or several branches need to stay open at once, the advantages of a dedicated worktree clearly win out.

The decisive difference is that a worktree does not touch your own work in progress at all: no stash that gets accidentally forgotten, no risk of a stash conflict when switching back later, and no need to restart running development processes. The table below summarizes the key differences.

10. Summary

11. FAQ: Worktree for Reviews