Use git worktree for parallel tasks

You know the feeling: you're deep into a feature branch when a hotfix request lands. Stashing, switching branches, or creating a second clone are all painful. git worktree solves this once and for all by letting you check out multiple branches of the same repository in separate directories at the same time — no stashing, no context switching, no duplicated clones. In this lesson, you'll learn how to use git worktree for parallel tasks, turning a frantic juggling act into a calm, organized workflow.

The problem this lesson solves

When you need to work on two tasks at once, the classic Git workflow forces you to make a choice:

• Stash and switch: Save your current work with git stash, switch to another branch, do the hotfix, commit, push, then switch back and pop your stash. Risky business — conflicts, forgotten stashes, and wasted mental energy.
• Clone the repo again: Create a full second clone in another folder. Obvious but wasteful: you duplicate the entire history, need to sync remotes, and your new clone isn't linked to your original repo.
• Work sequentially: Just wait until the current task is done. Slow, but sometimes survivable.

The problem is that Git is designed around a single working tree per repository. That single checkout is the bottleneck. You can have many branches, but you can only have one checked out at a time. This becomes especially painful when you need to:

• Apply a critical patch while your feature branch is mid-refactor.
• Run long-running tests on one branch while developing another.
• Compare behavior between two branches without merging them.
• Maintain a release branch while building the next version.

git worktree removes this bottleneck. Instead of juggling one working directory, you attach multiple working directories to the same Git repository — each with its own branch checked out. No stashing, no cloning, no switching. Just parallel workspaces.

Core concept / mental model

Think of a Git repository as a central brain (the .git folder) with multiple limbs (working trees). Normally, you have one limb attached, and you can only hold one branch at a time. git worktree lets you attach multiple limbs, each grabbing its own branch.

Key definitions:

• Main working tree: The original directory where you ran git clone or git init. This is your default working tree and is always associated with the repository.
• Linked worktree: An additional working directory created by git worktree add. Each linked worktree has its own checked-out branch and its own index, but they all share the same .git directory and object database.
• .git directory: The brain of the repository. It contains the commit history, branches, and configuration. Worktrees share this brain, so commits you make in one worktree are immediately visible to others.

Here's a visual representation in words:

Repository (.git)
├── main working tree (./my-project)         → branch: main
├── linked worktree (./my-project-hotfix)    → branch: hotfix/urgent-fix
└── linked worktree (./my-project-feature)   → branch: feature/new-login

All three directories point to the same repository, but each has its own branch checked out. Changes in one worktree don't affect the others until you commit and push.

Pro tip: Each worktree must be on a different branch. You cannot check out the same branch in two worktrees simultaneously.

How it works step by step

Using git worktree is a three‑step process: add, use, and remove.

1. Add a worktree

Navigate to your repository's root (the main working tree) and run:

git worktree add <path> <branch>

This creates a new directory at <path> and checks out the specified branch there. If the branch doesn't exist yet, Git creates it from your current HEAD. You can also specify a commit to start from:

git worktree add -b new-feature ../my-project-feature main

Here -b new-feature creates a new branch, ../my-project-feature is the path to the new worktree, and main is the base commit.

2. Work in the new worktree

Change into the new directory and start making commits. Everything you do in that directory is just like a normal repository: git status, git add, git commit, git push all work as usual. The only difference is that the branch is checked out in this directory only.

3. Remove a worktree when done

When you're finished with that task, you need to remove the worktree to keep things clean. This does not delete your branches or commits — it only removes the working directory. From your main working tree, run:

git worktree remove <path>

If you have uncommitted changes in that worktree, Git will refuse to remove it. Add --force to override, but only if you’re sure you don’t need those changes.

Key commands at a glance

Hands-on walkthrough

Let's make it concrete. We'll set up a demo repository, create a hotfix worktree, and see how parallel tasks work without conflicts.

Setup

First, create a simple repo and commit a base file:

mkdir worktree-demo && cd worktree-demo
git init
echo "print('Hello, world!')" > main.py
git add main.py && git commit -m "Initial commit"

Add a worktree for a hotfix

Now imagine your team needs an urgent fix. Create a linked worktree for it:

git worktree add -b hotfix/urgent ../worktree-demo-hotfix

The output shows:

Preparing worktree (new branch 'hotfix/urgent')
HEAD is now at 3f4a1c2 Initial commit

Notice the new directory ../worktree-demo-hotfix appeared, with hotfix/urgent checked out. Your original worktree-demo directory is still on main. Now you can work on both branches simultaneously.

Make commits in parallel

In the hotfix worktree, edit main.py and commit:

cd ../worktree-demo-hotfix
echo "print('Hello, hotfix!')" > main.py
git add main.py && git commit -m "Fix critical bug"

Meanwhile, back in the main worktree, develop a new feature without touching the hotfix:

cd ../worktree-demo
echo "print('Hello, feature!')" > main.py
git add main.py && git commit -m "Add feature"

Now both branches have different commits — and no worrying about stashing or losing work. You can see both worktrees:

git worktree list

/worktree-demo           3f4a1c2 [main]
/worktree-demo-hotfix    1234abc [hotfix/urgent]

Merge the hotfix back

After the hotfix is ready, you can merge it into main from the main worktree:

cd ../worktree-demo
git merge hotfix/urgent

Because both branches touch the same line, you'll get a conflict. This is a good reminder that worktrees don't avoid merge conflicts — they just let you develop branches in parallel without switching.

Cleaning up

When the hotfix is merged and pushed, remove the worktree:

cd ../worktree-demo
git worktree remove ../worktree-demo-hotfix

Your repository is back to a single working tree, clean and tidy.

Pro tip: Use git worktree prune to remove metadata for worktrees whose directories were deleted manually (for example, if you rm -rf the worktree folder).

Compare options / when to choose what

Worktrees are powerful, but they're not the only way to juggle tasks. Here's a comparison to help you decide:

When to choose worktrees:

• You need to work on two branches at the same time (feature + hotfix).
• You want to run tests on branch A while developing branch B.
• You're reviewing a pull request in a separate worktree without interrupting your main work.
• You want to keep a single remote and a single local sync — worktrees all push to the same origin.

When not to use worktrees:

• If you only need to switch briefly between tasks, a simple git switch might be faster.
• If disk space is extremely tight, each worktree is a full working copy (though objects are shared).
• If you're on a Git version older than 2.5 (unlikely today, but possible in legacy environments).

Troubleshooting & edge cases

Even with a solid mental model, you might hit a few snags. Here are common issues and how to fix them.

"fatal: '' is already checked out at ''"

You tried to check out a branch that's already checked out in another worktree. Git prevents this to avoid inconsistent states.

Fix: Choose a different branch for the new worktree, or remove the existing worktree first.

Worktree removal fails due to uncommitted changes

git worktree remove refuses to remove a worktree with modified files.

Fix: Commit or stash your changes in that worktree, or use git worktree remove --force if you really want to discard them.

Deleted the worktree directory manually

If you rm -rf a worktree directory, git worktree list will still show it. This causes confusion later.

Fix: Run git worktree prune to clean up stale metadata.

Forgot which worktree is which

With multiple worktrees, it's easy to lose track of what's where.

Fix: Use git worktree list with --porcelain for scriptable output, or add descriptive paths like ../my-project-hotfix instead of ../temp.

Merge conflicts are more likely?

Worktrees don't increase conflicts; they just make it easier to work on conflicting branches simultaneously. The same merge rules apply.

Fix: Communicate with your team, and use branches cleanly to minimize overlap.

What you learned & what's next

You can now use git worktree to handle parallel tasks with ease. You understand the core concept of linked working trees sharing a repository, you've performed the setup and teardown steps, and you know when to choose worktrees over stashing or cloning. You've also seen the troubleshooting pitfalls and how to avoid them.

You've met both learning objectives: you can explain the core idea behind git worktree for parallel tasks, and you've completed a practical exercise demonstrating it. This skill is a cornerstone of professional Git workflows — you'll use it daily when juggling hotfixes, features, and reviews.

Ready to keep building your Git muscle? The next lesson in this track will take you even deeper into advanced workflows. Stay tuned — you're about to unlock even more efficiency in your version control arsenal.

Final pro tip: Whenever you feel the urge to stash or clone just to work on two things at once, ask yourself: "Should I add a worktree instead?" The answer is often yes.