Parallel Development Without Cloning: Git Worktrees Explained

You are working on a long-running feature branch when an urgent bug fix request comes in. The traditional approach is to stash your changes, switch branches, fix the bug, commit, and then pop your stash back—only to deal with potential merge conflicts later. This workflow is disruptive and error-prone. Git worktrees offer a better solution by allowing you to work on multiple branches simultaneously in separate directories, all linked to a single repository.

Mechanics of Git Worktrees

Git worktrees let you check out multiple branches in separate working directories while sharing the same .git directory. This means:

• You avoid repeated cloning, saving disk space.
• Each worktree has its own working directory and index but shares objects and refs with the main repository.
• You can edit and commit changes in each worktree independently.

Worktrees are created with git worktree add and removed with git worktree remove. A key limitation is that you cannot check out the same branch in multiple worktrees simultaneously to prevent state corruption.

Worked Example: Hotfix Alongside Feature Work

Suppose you are working on feature/new-api and need to address a hotfix. Here is how to use worktrees to handle this without stashing:

1. Create the worktree:
Run this command from the root of your main project to create a new directory for the hotfix branch.

# Run from your main project directory
cd /path/to/your/main/project

# Create a new worktree for the hotfix branch
git worktree add ../hotfix-dir hotfix/urgent-bug

2. Work on the hotfix:
Navigate to the new worktree directory, make changes, and commit them.

cd ../hotfix-dir

# Make changes and commit
git add .
git commit -m "Fix urgent bug"
git push origin hotfix/urgent-bug

3. Clean up:
Once the hotfix is pushed, return to your main project and remove the worktree.

cd /path/to/your/main/project

# Remove the worktree
git worktree remove ../hotfix-dir

Your original feature/new-api branch remains untouched, with all uncommitted files intact.

Verification and Maintenance

To see all linked worktrees and their paths, use the list command:

git worktree list

Expected output:

• /path/to/main/project a1b2c3d [feature/new-api]
• /path/to/hotfix-dir e5f6g7h [hotfix/urgent-bug]

To ensure the main repository remains functional after removing a worktree, run:

git status
git log

Trade-offs and Limitations

While worktrees are powerful, they come with specific considerations:

• Orphaned Trees: Manually deleting a worktree folder instead of using git worktree remove leaves Git thinking the worktree exists. Use git worktree prune to clean up.
• Filesystem Dependencies: Keep worktrees on the same filesystem as the main repository for optimal performance and reliability.
• Locking: All worktrees share the repository lock, so operations like large fetches might be blocked if another worktree is performing a heavy operation.
• Garbage Collection: Avoid aggressive garbage collection while worktrees exist, as pruning can remove objects still referenced by other worktrees.

Git worktrees provide a streamlined way to manage parallel development without the overhead of repeated cloning or the risks of stashing. If you find yourself frequently switching branches or stashing changes, consider integrating worktrees into your workflow for a more efficient and less disruptive experience.