Managing Parallel Feature Development with Git Worktrees

The Problem: Context Switching Overhead

Developers often face a dilemma when a high-priority bug fix arrives while they are mid-way through a complex feature implementation. The traditional solution is to git stash changes or create a temporary "WIP" commit to clear the working directory before switching branches. This process is disruptive, prone to stash-pop conflicts, and makes it impossible to run a long-term test suite on one branch while continuing to code on another.

The takeaway: Git Worktrees allow you to have multiple branches checked out simultaneously in separate directories, all sharing a single .git history. This eliminates the need for stashing and allows for true parallel development without duplicating the entire repository on your disk.

The Minimal Design for Parallel Workflows

A worktree architecture consists of one main repository (the "main worktree") and one or more linked working trees. Unlike a full clone, a worktree does not duplicate the object store; it creates a new directory with its own index and HEAD, but points back to the original .git directory for all versioning data.

To implement the smallest suitable design for a parallel task, use the following command from your main project root:

# Syntax: git worktree add <path> <branch>
# Example: Create a directory for a hotfix branch
git worktree add ../hotfix-branch hotfix-issue-123

This creates a directory named hotfix-branch one level above your current project. You can now cd into that directory and work independently of your feature branch.

Trust and Data Boundaries

While worktrees provide filesystem isolation, they share a critical data boundary: the underlying Object Store. Because all worktrees reference the same .git folder, any commit made in one worktree is immediately available to all others.

• Isolated: The Index (staging area) and the Working Tree (the actual files).
• Shared: The Commit History, Tags, and Remote Tracking branches.

A key constraint of this design is that Git prevents the same branch from being checked out in two different worktrees simultaneously. This prevents index corruption and conflicting HEAD updates.

Operational Checks and Verification

Before adding a worktree, ensure the target path is empty and does not contain its own .git directory. To manage and verify your current environment, use the following commands:

Listing Active Worktrees

Run this from any linked directory to see all active paths and their associated branches:

git worktree list

Verification Workflow

1. Create a test worktree: git worktree add ../test-wt feature-branch.
2. Navigate to ../test-wt and run git branch to confirm the active branch.
3. Modify a file in ../test-wt and verify that the file in the main repository remains unchanged.

Failure Modes and Recovery

The primary risk with worktrees is orphaned metadata. If you delete a worktree directory using rm -rf instead of the Git command, the main repository still believes the worktree exists and holds a lock on the associated branch.

Correct Removal

Always use the built-in removal command to clean up the administrative files in the .git directory:

# Run from the main repository root
git worktree remove ../hotfix-branch

Handling Manual Deletion

If a directory was deleted manually, you must prune the metadata to unlock the branch:

git worktree prune

Design Limitations and Constraints

Constraint	Impact	Mitigation
Single Branch Lock	Cannot check out 'main' in two places.	Create a temporary branch for the second worktree.
Network Filesystems	NFS/CIFS may cause stale file handles.	Keep worktrees on local SSDs.
Case-Insensitivity	Path mismatches on macOS/Windows.	Use consistent naming conventions for paths.

This architecture should be evolved into a full clone only if you require completely isolated configurations (e.g., different .git/config settings) or if you are working across different physical machines.