git worktree cheatsheet

01 Mental Model

A worktree is a linked working directory that shares the same .git object store as your main repo. Each worktree checks out a different branch. You can build, test, and edit in parallel — no stashing, no context-switching overhead.

02 Bare Clone Setup (Recommended)

The cleanest worktree workflow starts from a bare clone. A bare repo has no working directory of its own — it only holds the .git internals. Every branch you work on becomes an explicit worktree. This avoids the confusion of having a "main" working directory that is structurally different from the others.

# Clone as bare — the directory IS the .git store
git clone --bare git@github.com:org/myproject.git myproject
cd myproject

# Fix fetch refspec so 'git fetch' works properly
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

# Now add worktrees for the branches you need
git worktree add main
git worktree add develop
git worktree add feature/cardiac-mesh

Non-bare alternative (simpler, less clean)

You can also add worktrees from a normal clone. The original checkout remains and sibling worktrees live alongside it or elsewhere.

git clone git@github.com:org/myproject.git
cd myproject
git worktree add ../myproject-feature feature/cardiac-mesh

03 Core Commands

Create a worktree

# Checkout an existing branch into a new directory
git worktree add <path> <branch>

# Create a new branch AND its worktree in one step
git worktree add -b <new-branch> <path>

# Create from a remote branch (auto-tracks)
git worktree add <path> origin/feature-x

# Detached HEAD worktree (useful for inspecting a tag/commit)
git worktree add --detach <path> <commit-ish>

List worktrees

git worktree list
/home/user/myproject         (bare)
/home/user/myproject/main    abc1234 [main]
/home/user/myproject/develop def5678 [develop]

Remove a worktree

# Clean removal (fails if there are uncommitted changes)
git worktree remove <path>

# Force removal (discards uncommitted changes)
git worktree remove --force <path>

# If you manually deleted the directory, clean up the bookkeeping
git worktree prune

Move a worktree

git worktree move <old-path> <new-path>

04 CMake / C++ Workflow

This is where worktrees genuinely shine. With a normal git checkout, switching branches invalidates your entire build directory because the source tree changed under CMake's feet. With worktrees, each branch has its own source and build directory, so builds are always warm.

Recommended layout

Setting up a C++ worktree from scratch

cd myproject
git worktree add feature/cardiac-mesh
cd feature/cardiac-mesh

# Configure & build in-tree build/ directory
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Out-of-tree builds (alternative)

If you prefer keeping build artefacts separate from source:

cmake -B ../myproject-builds/feature-cardiac-mesh -S .

05 Python / General Workflow

For Python, worktrees are less about build directories and more about keeping separate virtual environments per branch, or running tests on one branch while editing another.

Per-worktree virtual environments

cd myproject/feature-refactor
python -m venv .venv
source .venv/bin/activate
pip install -e .    # editable install for this branch

Typical use cases beyond C++

Running a long test suite on main while developing on a feature branch. Reviewing a colleague's PR in an isolated directory without disrupting your work. Comparing behaviour across two branches side-by-side in separate terminals.

06 Directory Layouts Compared

07 Common Operations

Fetching & pulling across worktrees

# Fetch is repo-wide — run it from anywhere
git fetch --all

# But pull is per-worktree (it merges into the current HEAD)
cd main && git pull
cd ../develop && git pull

Cherry-picking between worktrees

# From the target worktree, cherry-pick by commit hash
cd hotfix
git cherry-pick abc1234

# Or reference a branch (commits are shared across all worktrees)
git cherry-pick feature/cardiac-mesh~2

Rebasing a feature branch

# Step into the feature worktree
cd feature/cardiac-mesh
git rebase main

# main's worktree doesn't need to be "current" for this —
# the ref is shared from the repo's object store

Checking what is where

# Which branch is checked out in each worktree?
git worktree list

# Detailed info (shows locked/prunable status)
git worktree list --verbose

Locking a worktree (prevent pruning)

# Useful if a worktree is on an external drive or NFS mount
git worktree lock <path>
git worktree unlock <path>

08 Gotchas & Pitfalls

09 Hooks & Automation

Auto-setup script for CMake worktrees

#!/usr/bin/env bash
# wt-add.sh — create a worktree and configure its build
# Usage: ./wt-add.sh <branch> [cmake-args...]

BRANCH="${1:?Usage: wt-add.sh  [cmake-args...]}"
shift
WT_PATH="${BRANCH//\//-}"   # feature/foo → feature-foo

git worktree add "$WT_PATH" "$BRANCH" || exit 1
cd "$WT_PATH"

# Auto-configure CMake build
cmake -B build -S . "$@"
echo "Worktree ready: $WT_PATH (branch: $BRANCH)"

post-checkout hook (per-worktree)

Git hooks live in the shared .git/hooks/ (or bare repo hooks/) and fire for all worktrees. You can use the $GIT_DIR environment variable inside hooks to determine which worktree triggered them.

#!/usr/bin/env bash
# .git/hooks/post-checkout
# Re-run cmake configure after branch switch

OLD_HEAD="$1"
NEW_HEAD="$2"
BRANCH_CHECKOUT="$3"  # 1 if branch checkout, 0 if file checkout

if [ "$BRANCH_CHECKOUT" = "1" ] && [ -f "CMakeLists.txt" ]; then
    echo "Branch changed — reconfiguring CMake..."
    cmake -B build -S .
fi

Shell alias for quick worktree navigation

# Add to .bashrc / .zshrc
alias wtl='git worktree list'
alias wta='git worktree add'
alias wtr='git worktree remove'

# fzf-powered worktree switcher
wt() {
    local target
    target=$(git worktree list | fzf --height=40% | awk '{print $1}')
    [ -n "$target" ] && cd "$target"
}

10 Quick Reference Table