Managing Parallel Tasks with Git Worktree

The Problem: Context Switching Friction

When working on a long-term feature branch, an urgent bug fix often requires you to stop everything. The traditional workflow involves either git stash to save your current progress or committing unfinished work to a temporary branch. Both methods introduce friction: you must remember what was stashed, manage a cluttered stash list, or deal with "work-in-progress" commits that pollute your history.

The solution is Git Worktree. It allows you to have multiple physical directories (worktrees) linked to a single local repository. Instead of switching branches within one directory, you open a second directory for the bug fix while your feature branch remains untouched and open in your IDE.

How Git Worktree Operates

Normally, a Git repository has one working tree (the files you see) and one index (the staging area). A worktree expands this by allowing multiple working trees and multiple indices, all sharing the same .git directory (the object database). This means you don't need to re-clone the repository to work on a different branch; all branches and commits are already available across all worktrees.

Worked Configuration: Adding a Parallel Worktree

Assume you are currently in your main project directory /projects/app-main on the feature-ui branch. You need to fix a critical bug on main.

Run the following command from the root of your repository:

# Syntax: git worktree add <path> <branch>
# Run this in /projects/app-main
git worktree add ../app-hotfix main

What happens next:

• Git creates a new directory at /projects/app-hotfix.
• It checks out the main branch into that directory.
• It creates a administrative link in the main repository's .git/worktrees folder to track the state of the new directory.

You can now cd ../app-hotfix, apply your fix, commit, and push. When finished, you simply return to /projects/app-main, and your feature-ui work is exactly where you left it.

Operational Constraints and Limits

While powerful, worktrees have specific technical boundaries to prevent repository corruption:

• Branch Exclusivity: Git prevents you from checking out the same branch in two different worktrees. If you try to git checkout a branch that is already active in another worktree, Git will block the operation. While --force can override this, it is risky as it can lead to inconsistent index states and confusing HEAD references.
• Directory Hierarchy: You cannot create a worktree inside another worktree's directory or inside the main repository's .git folder.
• Shared Object Database: Because all worktrees share the same .git directory, any operation that modifies the global object database (like git gc or pruning) affects all worktrees.

Common Mistakes and Diagnostics

The "Ghost" Worktree

A common mistake is deleting a worktree directory using rm -rf or a file explorer. This removes the files but leaves a stale reference in the main repository's administrative files. Git will still think the worktree exists, preventing you from checking out that branch elsewhere.

The Fix: Use the built-in removal command to clean up both the files and the metadata:

# Run from the main repository
git worktree remove <path-to-worktree>

If you have already deleted the folder manually, run the following to clear stale references:

git worktree prune

Path Fragility

If you move the parent directory containing your worktrees, the relative paths stored in .git/worktrees may break. If Git reports that a worktree is missing, verify the path using git worktree list.

Verification Checklist

To verify your worktree is configured correctly, perform these checks:

1. Path Check: Run git worktree list. You should see the absolute paths to both your main directory and the added worktree.
2. Identity Check: Inside the worktree directory, run git rev-parse --git-dir. It should point back to the .git folder of the original main repository, not a local .git folder.
3. Branch Check: Run git status in both directories. They should report different active branches.