Git Worktree Guide

Git-Worktree.md

Frequently Used Git Worktree Commands

Basic Operations

git worktree add <path> <branch>         # Create worktree for a branch that already exists in the repo
git worktree add -b <new-branch> <path>  # Create worktree with new branch
git worktree list                        # List all worktrees
git worktree remove <path>               # Remove a worktree

Examples

# Work on a feature branch in a separate directory
# <path> is the folder, <branch> is the branch checked out in that worktree
# e.g., ../feature-login is the folder, feature/login is the branch
git worktree add ../feature-login feature/login

# Create a new branch and worktree at once
git worktree add -b bugfix/issue-42 ../bugfix-42

# Quick hotfix from main
git worktree add ../hotfix main

# Clean up when done
git worktree remove ../hotfix

# Force remove (if worktree has changes)
git worktree remove --force ../hotfix

Branch Constraint Examples

# The main repo directory is itself a worktree (the "main worktree").
# A branch CANNOT be checked out in more than one worktree (including the main worktree).

# Example: main worktree is on "main"
git worktree add ../hotfix main
# ERROR: fatal: 'main' is already checked out at '/path/to/main-repo'

# Example: main worktree is on "feature/login"
git worktree add ../hotfix feature/login
# ERROR: fatal: 'feature/login' is already checked out at '/path/to/main-repo'

# To create a worktree based on the current branch, you MUST use -b to create a new branch:
# (assuming main worktree is on "main")
git worktree add -b hotfix/fix-123 ../hotfix        # new branch based on current HEAD (main)
git worktree add -b hotfix/fix-123 ../hotfix main    # explicitly base on main (same result)

Merge Worktree into Main Worktree, Then Delete

# Scenario: you've been working in a worktree on branch "hotfix/fix-123"
# and want to merge it back into "main" (the main worktree's branch)

# 1. Go to the main worktree
cd /path/to/main-repo

# 2. Merge the worktree's branch
git merge hotfix/fix-123

# 3. Remove the worktree (the directory and its link)
git worktree remove ../hotfix

# 4. Optionally delete the branch (it's no longer needed)
git branch -d hotfix/fix-123

Rename a Worktree

# There is NO `git worktree rename` command.
# Instead, move the directory and then repair the references:

mv ../hotfix ../hotfix-renamed
git worktree repair ../hotfix-renamed

# `git worktree repair` updates the internal links between the repo and the moved worktree

Make a Worktree Branch Available on the Main Worktree (Switch Without Merging)

# Scenario: you want to switch the main worktree to the worktree's branch
# (e.g., to continue work there instead of in the worktree)

# 1. Remove the worktree's directory first (you can't checkout a branch that's in use by another worktree)
git worktree remove ../hotfix

# 2. Now checkout that branch in the main worktree
git checkout hotfix/fix-123

# Note: the branch and all its commits still exist after removing the worktree.
# Removing a worktree's directory does NOT delete the branch.
# This is true even if the branch was created with -b during `git worktree add`.
# Branches live in the shared .git repo (refs), not in the worktree directory.

Maintenance

git worktree prune          # Clean up stale worktree references (e.g., manually deleted dirs)
git worktree lock <path>    # Prevent a worktree from being pruned
git worktree unlock <path>  # Unlock a locked worktree

Key Points

• Each worktree must be on a different branch — you can't check out the same branch in two worktrees
• The main repo directory counts as a worktree (the "main worktree"), so this constraint applies to it too
• To create a worktree from the current branch, you must use -b to create a new branch name
• The <path> (directory name) and <branch> are independent — the folder name doesn't have to match the branch
• Worktrees share the same .git repository (objects, refs, etc.), so they're lightweight
• A worktree is a fresh checkout of the specified branch — it contains all git-tracked files from that branch
• Common use case: review a PR or fix a bug without stashing/switching your current work