Skip to content

01-worktrees.md

Latest commit

 

History

History
101 lines (75 loc) · 3.18 KB

01-worktrees.md

File metadata and controls

101 lines (75 loc) · 3.18 KB

Episode 1: Git Worktrees 🌳

The hidden gem: Work on multiple branches simultaneously without stashing or cloning.

The Problem

You're deep in a feature branch, files changed everywhere, and someone asks you to review a hotfix on main. Your options?

  • git stash → switch → review → switch back → git stash pop (messy, fragile)
  • Clone the repo again (wasteful, slow)
  • git worktree → instant parallel checkout, zero disruption ✨

What is git worktree?

A worktree is an additional working directory linked to the same .git database. Each worktree checks out a different branch. They share history, remotes, and config — but each has its own working files and index.

repo/                  ← your main worktree (feature-branch)
repo-hotfix/           ← linked worktree (main branch)
repo-experiment/       ← linked worktree (experiment branch)

One .git, multiple working directories. Mind = blown.

Key Commands

# Add a worktree for an existing branch
git worktree add ../hotfix-tree main

# Add a worktree AND create a new branch
git worktree add -b bugfix/issue-42 ../bugfix-tree main

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../hotfix-tree

# Prune stale worktree references
git worktree prune

The Rules

  1. Each branch can only be checked out in ONE worktree at a time. Git enforces this.
  2. Worktrees share the object database — no wasted disk space.
  3. Each worktree has its own HEAD, index, and working directory.
  4. Worktrees are local only — they don't affect remotes or collaborators.

Real-World Scenarios

Scenario A: Parallel development

You're building a feature on feature/search but need to fix a bug on main:

git worktree add ../hotfix main
cd ../hotfix
# fix the bug, commit, push
cd ../gitfoo_episode_1
git worktree remove ../hotfix

Your feature branch is completely untouched.

Scenario B: Running tests on two branches simultaneously

git worktree add ../test-main main
git worktree add ../test-feature feature/new-ui
# Run test suites in parallel in separate terminals

Scenario C: Code review without context-switching

git worktree add ../review origin/pull-request-123
cd ../review
# read the code, run it, test it

Pro Tips

  • Name worktree dirs clearly — include the branch name or purpose.
  • Use git worktree list to see what you have checked out and where.
  • Combine with git bisect (Episode 2) — bisect in a worktree while your main tree stays clean.
  • Worktrees are perfect for CI/CD scripts that need to build multiple branches.

Run the Demo

bash episodes/demos/01-worktrees-demo.sh

Cheat Sheet

Command What it does
git worktree add <path> <branch> Create a new worktree
git worktree add -b <new> <path> <start> Create worktree + new branch
git worktree list Show all worktrees
git worktree remove <path> Remove a worktree
git worktree prune Clean up stale references
git worktree lock <path> Prevent a worktree from being pruned
git worktree move <path> <new-path> Relocate a worktree