Git Worktrees for Multiple Checkouts

Use git worktree to work with multiple branches at once.

Managing multiple branches in a single Git repository can often lead to workflow bottlenecks. Context switching between branches, especially when working on urgent hotfixes alongside long-lived feature branches, is tedious and error-prone. Fortunately, Git offers a built-in solution: worktrees.

What Is a Git Worktree?

A worktree is an additional working directory, attached to your repository, that lets you check out a branch independently from your main working directory. With git worktree, you can have several working trees linked to the same repository, all pointing to different branches or commits.

This eliminates the need for multiple clones of a repository and makes working with parallel tasks much smoother.

Why Use Worktrees?

Here are some scenarios where git worktree shines:

  • Feature and Hotfix Development: Switch to a hotfix branch in a new worktree, fix the bug, and continue working on your feature branch in the original directory.
  • Code Reviews: Check out pull requests in separate directories without disrupting ongoing work.
  • Testing Builds: Experiment in a fresh worktree with a clean state.
  • Documentation Updates: Work on docs in parallel without losing context in your code branch.

Setting Up Your First Worktree

Let's walk through a typical worktree workflow.

1. Create a New Branch

Suppose you're working on feature-x but need to quickly switch to hotfix-1.

git checkout feature-x

2. Add a Worktree

Create a new worktree in a subdirectory (../hotfix-1-dir) based on hotfix-1:

git worktree add ../hotfix-1-dir hotfix-1

If hotfix-1 doesn't exist yet:

git worktree add -b hotfix-1 ../hotfix-1-dir origin/main

This creates a new directory containing a checkout of hotfix-1, fully tracking the same repository.

3. Work in Separate Directories

Now, you have:

  • your-repo/ working on feature-x
  • hotfix-1-dir/ working on hotfix-1

Each directory operates independently. You can run builds, commits, and Git commands as usual.

4. List Existing Worktrees

View all current worktrees:

git worktree list

Example output:

/home/user/repos/your-repo    f8a1d67 [feature-x]
/home/user/hotfix-1-dir       9321abc [hotfix-1]

5. Remove a Worktree

When you’re done, remove the additional worktree safely:

rm -rf ../hotfix-1-dir
git worktree prune

This deletes the directory and cleans up metadata.

Advantages Over Multiple Clones

  • Saves Disk Space: All worktrees share the same repository objects.
  • Central Remote Management: One .git repository manages remotes and configs.
  • Improved Context: Each worktree is branch-specific, minimizing accidental commits to wrong branches.
  • Lightweight: Worktrees are faster to create and easier to clean up than clones.

Tips and Best Practices

  • Don't Overlap Worktrees: Always use separate directories for each worktree.
  • Detached HEADs: You can use worktrees for temporary or experimental checkouts, too.
  • Safe Deletion: Always remove worktrees using rm or via the git worktree remove command, then prune.

Conclusion

The git worktree command is a powerful addition to every developer’s toolkit. It helps you stay productive, focused, and efficient when working across multiple branches. Whether you’re triaging bugs, reviewing code, or managing releases, worktrees offer a safe and streamlined solution for parallel development.

Try integrating worktrees into your workflow—your future self will thank you!

Further Reading:

Back to All Articles