Why worktrees enable parallel work in Git - Why It Works

Introduction

Sometimes you want to work on different features or fixes at the same time without mixing changes. Git worktrees let you have multiple working folders linked to the same repository, so you can work on different branches side by side.

When you want to develop a new feature while keeping your current work untouched.

When you need to test a bug fix on a separate branch without disturbing your main code.

When you want to review or build a different branch without switching your current workspace.

When you want to run multiple versions of your project simultaneously for comparison.

When you want to avoid the hassle of stashing or committing unfinished work before switching branches.

Commands

This command creates a new working directory outside your main repo folder at ../feature-branch and checks out the 'feature' branch there. It lets you work on 'feature' branch in parallel.

Terminal

git worktree add ../feature-branch feature

Expected Output

Preparing worktree (checking out 'feature')

HEAD is now at abc1234 Commit message on feature branch

This lists files in the new worktree folder to confirm the branch files are checked out separately.

Terminal

ls ../feature-branch

Expected Output

README.md

src

.gitignore

Shows all active worktrees linked to your repository, so you can see where each branch is checked out.

Terminal

git worktree list

Expected Output

/home/user/myrepo               abc1234 [main]

/home/user/feature-branch       abc1234 [feature]

Removes the worktree at ../feature-branch when you finish working on that branch, cleaning up the extra folder.

Terminal

git worktree remove ../feature-branch

Expected Output

Deleted worktree ../feature-branch

Key Concept

Git worktrees let you have multiple folders with different branches checked out, so you can work on them side by side without switching or losing changes.

Common Mistakes

Trying to create a worktree for a branch that does not exist yet.

Git cannot check out a branch that does not exist, so the command fails.

Create the branch first with 'git branch branch-name' or use 'git worktree add -b branch-name path origin/branch-name' to create and check out at once.

Deleting the worktree folder manually without using 'git worktree remove'.

Git still thinks the worktree exists and may cause errors or confusion.

Always remove worktrees using 'git worktree remove path' to keep Git's metadata clean.

Working inside the main repo folder on a branch that is checked out in a worktree.

This can cause conflicts or confusion because the same branch is checked out in two places.

Avoid checking out the same branch in multiple worktrees or the main repo folder at the same time.

Summary

Use 'git worktree add' to create a new folder with a different branch checked out for parallel work.

Check active worktrees with 'git worktree list' to see all your parallel branches.

Remove worktrees cleanly with 'git worktree remove' to avoid leftover folders and metadata.