How to Use Git Worktrees for Parallel Branches

In this tutorial, you'll learn about How to Use Git Worktrees for Parallel Branches. We cover key concepts, practical examples, and best practices.

The Problem

You're working on a feature branch and need to urgently fix a bug on main. You have unstaged changes, pending builds, or open editors. Stashing, committing, or force-closing everything is disruptive. Git worktrees let you check out different branches in separate directories so you can work on them simultaneously. Each worktree has its own working directory, index, and staging area, but shares the same .git database.

Quick Fix

1. Create a new worktree

git worktree add ../hotfix hotfix-branch

This creates a new directory ../hotfix with hotfix-branch checked out. The original repo directory stays on whatever branch it was on.

2. List all worktrees

git worktree list

Expected output:

/home/user/project        main
/home/user/project-hotfix hotfix-branch
/home/user/project-docs   docs/readme-update

The first column is the path, the second is the checked-out branch.

3. Create a worktree from a specific commit

git worktree add ../release-v2 abc1234

This creates a detached HEAD at commit abc1234. Use git worktree add -b new-branch ../path starting-point to create a new branch at the commit.

4. Remove a worktree

git worktree remove ../hotfix

If the worktree has uncommitted changes, use --force:

git worktree remove ../hotfix --force

5. Prune stale worktree metadata

git worktree prune

If you deleted a worktree directory manually (without git worktree remove), Git still tracks it internally. Pruning cleans up this stale metadata.

6. Use worktrees for parallel feature work

# In the main repo
git worktree add ../feature-auth feature/authentication
git worktree add ../feature-payments feature/payments

Each worktree is a full working directory with its own editor, build artifacts, and git state.

7. Push from a worktree

# Inside ../hotfix directory
git push origin hotfix-branch

Worktrees share the same remote configuration as the main repository. Pushing, pulling, and fetching work identically.

8. Clean up after merging

cd /home/user/project
git branch -d hotfix-branch
git worktree remove ../hotfix

Always remove the worktree directory before deleting the branch to avoid orphaned worktree references.

9. Move a worktree to a different location

# Move the worktree directory
mv ../hotfix ../hotfix-bugfix
# Update git's reference
git worktree repair ../hotfix-bugfix

If you need to rename a worktree directory, use git worktree repair to update the internal git metadata that tracks the worktree path.

Prevention

• Create a naming convention: ../project-feature-name for worktree directories
• Remove worktrees with git worktree remove, not rm -rf
• Run git worktree prune after manual directory deletions to clean up metadata
• Avoid creating worktrees inside the main repo directory
• Use worktrees instead of git stash for quick context switches
• Remember: the main repo and all worktrees share the same remote configuration — pushing from any worktree is identical to pushing from the main repo