main NOW.# Without worktrees: stash, checkout main, fix, commit, push,
# checkout feature, stash pop, hope nothing went wrong.
# With worktrees:
git worktree add ../my-project-hotfix main
cd ../my-project-hotfix
# Fix the bug, commit, push
git push origin main
cd -
git worktree remove ../my-project-hotfix
# Your feature worktree is untouched. Zero context switch.cd-ing to a different directory, not by mutating your workspace.main branch stays checked out in the main worktree — the hotfix worktree exists only for the duration of the fix.
# Fetch the PR and create a review worktree:
git fetch origin pull/42/head:pr-42
git worktree add ~/dev/worktrees/review-42 pr-42
# Review the code in isolation:
cd ~/dev/worktrees/review-42
# Read, test, leave comments...
# When done:
cd -
git worktree remove ~/dev/worktrees/review-42
git branch -D pr-42# Create a dedicated bisect worktree:
git worktree add ../my-project-bisect main
cd ../my-project-bisect
# Run the bisect:
git bisect start
git bisect bad HEAD
git bisect good v2.5.0
# Test each commit...
git bisect run npm test # automated
# or test manually:
git bisect good # or git bisect bad
# When found, record the commit hash and clean up:
git bisect reset
cd -
git worktree remove ../my-project-bisectgit bisect checks out different commits as it narrows the search. In a normal repo, this destroys your working tree state. A bisect worktree isolates the bisection — your main worktree stays on your feature branch, untouched.git bisect modifies HEAD in the bisect worktree only. The shared refs mean the bisect state (refs/bisect/*) is technically visible everywhere, but the checkout changes only affect the bisect worktree's working tree. Other worktrees are unaffected.
# Create a sandbox worktree for the experiment:
git worktree add ~/dev/worktrees/experiment-refactor -b experiment/refactor-core
cd ~/dev/worktrees/experiment-refactor
# Try wild things. Rewrite the core module. Delete half the codebase.
# If it works:
git push origin experiment/refactor-core
# Open a PR, get feedback.
# If it fails:
cd -
git worktree remove --force ~/dev/worktrees/experiment-refactor
git branch -D experiment/refactor-core
# No trace left behind.mainmain always checked out and clean, available at a moment's notice.# Set up once:
git worktree add ~/dev/worktrees/main main
# Your workflow:
# - Main worktree: your current feature branch (changes daily)
# - ~/dev/worktrees/main: always on main, always clean, always up to date
# Before starting any merge:
cd ~/dev/worktrees/main
git pull origin main
cd ~/dev/my-project
git merge main # main worktree now has latest main merged inmain always available in a dedicated worktree eliminates the "what branch am I on?" friction when you need to check something on main. It also serves as a clean reference point — you can always diff your feature branch against the known-good main checkout.# Your setup (one-time):
# Main worktree (~/dev/my-project): your "control tower" — main branch
# Worktree ~/dev/worktrees/agent-1: feat/dark-mode
# Worktree ~/dev/worktrees/agent-2: fix/login-timeout
# Worktree ~/dev/worktrees/agent-3: refactor/api-layer
# Agent workflow (per agent):
# 1. Agent works in its assigned worktree
# 2. Agent commits and pushes its branch
# 3. You review from the main worktree
# 4. You merge from the main worktree
# 5. You remove the agent's worktree
# Script helper:
agent-worktree() {
local agent="$1"
local branch="$2"
local path="$HOME/dev/worktrees/agent-$agent"
git worktree add "$path" -b "$branch" && echo "Agent $agent ready at $path"
}
agent-done() {
local agent="$1"
git worktree remove "$HOME/dev/worktrees/agent-$agent"
}main, receives merges, and never has WIP. You can spin up or tear down agent worktrees in seconds.# CI says commit abc1234 is broken. Reproduce locally:
git worktree add --detach ~/dev/worktrees/ci-debug abc1234
cd ~/dev/worktrees/ci-debug
# Reproduce the failure, debug, find the fix.
# Create a branch from here if needed:
git switch -c fix/ci-regression
# Apply the fix, push, create PR.
cd -
git worktree remove ~/dev/worktrees/ci-debugAfter this course, here's what a well-organized worktree setup looks like for daily agentic coding:
main, always clean. You merge, review, and coordinate from here. All other worktrees are temporary — created for a specific task, removed when done. The main worktree is the one long-running exception because having main always at hand is that useful.
| Lesson | Core takeaway |
|---|---|
| 0000: Mental Model | A worktree is an additional working tree attached to the same .git. Shared database, isolated workspace. The .git in a linked worktree is a pointer file. |
| 0001: Creating & Listing | git worktree add creates a worktree in under a second. git worktree list is your dashboard. git worktree remove cleans up safely. |
| 0002: Working in Parallel | One worktree per agent per branch. The lifecycle is: create → work concurrently → merge → cleanup. Wrap it in shell functions. |
| 0003: Edge Cases | Rebase coordination, detached HEAD, orphaned metadata, branch conflicts, merge conflicts. Your diagnostic toolkit: git worktree list, ls .git/worktrees/, cat .git. |
| 0004: Advanced Patterns | Hotfix interrupt, code review worktree, bisect worktree, experiment sandbox, long-running main, multi-agent hub, CI debug. |
cd replaces git checkout.rm -rf, prune periodically, coordinate rebases.Primary source: Git Worktrees: A Practical Guide — The GitHub Blog covers several of these patterns. The official docs have full flag documentation for every command used.
Going further: Explore git-bisect for automated bisection, and consider integrating worktree creation into your agent orchestration scripts.
Ask questions: "How do I integrate worktrees with my specific agent orchestration setup?" or "What's the best way to share worktree conventions across a team?" — your agent-teacher can help you adapt these patterns to your exact workflow.