1. Home
2. web
3. Using git worktree for Concurrent Branch Development

Introduction

In daily software development, it is common to get interrupted by an urgent hotfix request while in the middle of writing code for a feature branch.

Traditionally, developers handle this in one of two ways:

1. Temporarily shelf active changes using git stash, switch branches to fix the bug, commit, switch back, and run git stash pop.
2. Clone a completely separate copy of the repository into another directory to work on the hotfix.

However, stash runs the risk of conflict errors on restore, and cloning multiple copies of the same repository wastes disk space and complicates local commit synchronization.

The native git worktree command solves this problem. This article explains how to use git worktree to work on multiple branches concurrently without context-switching friction.

1. What is git worktree?

git worktree is a native Git feature that allows you to checkout multiple branches into separate directories on your machine, all linked to a single underlying .git repository.

Core Benefits

• No More Stashing: You can leave your active workspace as-is and jump straight into hotfixes by switching to a different folder.
• Disk Space Savings: Because all directories share a single .git history cache, the disk overhead is minimal compared to cloning the repository multiple times.
• Preserved Build Caches: Separate directories mean compiler caches (such as Vite, Webpack, or Next.js build outputs) remain intact. You avoid the compile delays associated with switching branches back and forth.

2. Basic Steps to Use git worktree

Let’s walk through creating and using a worktree for parallel development.

Directory Layout

Your project workspaces will be structured like this:

/my-project/ (Primary workspace: working on your feature branch)
/my-project-hotfix/ (Linked worktree workspace: checking out the hotfix branch)

Step 1: Add a Linked Worktree

From your primary workspace directory (/my-project/), run the following command to check out a new branch in a separate folder:

# git worktree add <target-path> <branch-name>
# Use the -b flag if you need to create a new branch
git worktree add ../my-project-hotfix -b hotfix/critical-bug

This creates a new sibling folder named my-project-hotfix with the hotfix/critical-bug branch checked out and ready.

Step 2: Switch Folders and Work

Navigate to the new folder, make your changes, commit, and push them to the remote repository.

cd ../my-project-hotfix
# Resolve the bug
git add .
git commit -m "fix: resolve critical production bug"
git push origin hotfix/critical-bug

Your uncommitted changes in the primary my-project folder remain untouched.

Step 3: Remove the Worktree

Once the hotfix is pushed and merged, you can safely delete the temporary worktree.

Navigate back to your primary repository directory and run the cleanup command:

cd ../my-project

# List all active worktrees
git worktree list

# Remove the linked worktree (this also deletes the physical directory)
git worktree remove ../my-project-hotfix

The workspace is now clean.

3. Important Constraint

When working with git worktree, keep this rule in mind:

📌 Important

You cannot check out the same branch in multiple active worktrees at the same time.

For instance, if your primary workspace has the main branch checked out, attempting to run git worktree add ../another-path main will fail. This safety guard prevents conflicting commit tracking in your local history.

Conclusion

The git worktree command is an essential tool for managing parallel tasks without losing your place in your codebase.

1. Create a separate directory for urgent tasks using git worktree add.
2. Commit your changes and delete the folder using git worktree remove.

Incorporate git worktree into your Git workflow to simplify context-switching and improve development speed.