Video 22.1: Git Worktrees Explained

Course: Claude Code - Parallel Agent Development (Course 4) Section: S22 - Git Worktrees and Manual Patterns Video Length: 4-5 minutes Presenter: Daniel Treasure

Opening Hook

If you're trying to run multiple Claude Code agents in parallel on the same project, branching alone isn't enough. Git worktrees give you what you actually need: separate, independent working directories that all share the same Git history. Let's explore how they work and why they're the perfect foundation for parallel AI development.

Key Talking Points

What to Say: Conceptual Foundation

The problem with just branching: Branches let you track separate work, but they don't give you separate working directories. You can only check out one branch at a time in a single directory.
What a worktree solves: A worktree is a separate working directory that's "linked" to your main .git database. You can have multiple worktrees checked out simultaneously, each on a different branch, without interfering with each other.
Shared foundation: All worktrees share the same .git directory, which means they see the same commit history, refs, and tags. But they have completely independent file states.
Why this matters for AI agents: Each Claude Code session can run in its own worktree, working on its assigned branch with full isolation. One agent modifying files in worktree-A doesn't affect the files in worktree-B.
Practical difference from just cloning: Cloning the repo multiple times wastes disk space and creates confusing duplicate histories. Worktrees are lightweight and intentional — they're designed for exactly this use case.

What to Show on Screen: Git Worktree Basics

Start with a simple repo already initialized with some commits
Show the .git directory structure briefly (not deep dive, just: "all worktrees share this one .git")
Demonstrate git worktree list on a fresh repo (should show just the main one)
Create a new worktree with git worktree add
Show the new directory on disk
Run git worktree list again (both worktrees now visible)
Switch to the new worktree directory and verify: different branch, same Git history

Demo Plan

Timing: ~2.5 minutes for demo

Step 1: Prepare the Repository (30 seconds)

Open terminal in an existing Git repository with a few commits
Run: git log --oneline | head -5 to show existing history
Run: git branch -a to show current branches

Step 2: Inspect Current Worktrees (20 seconds)

Run: git worktree list
Explain the output: shows the main worktree path and the current branch

Step 3: Create a New Worktree (45 seconds)

Create a feature branch first (or use an existing one):
git checkout -b feature/auth-system (if branch doesn't exist)
git checkout feature/auth-system (if it does)
Go back to main: git checkout main
Create a worktree linked to the feature branch:
git worktree add ../auth-worktree feature/auth-system
Explain what just happened: git created a new directory at ../auth-worktree with the feature branch checked out

Step 4: Verify Independence (45 seconds)

In current terminal (main worktree), show a file: ls -la or cat README.md
Navigate to the new worktree: cd ../auth-worktree
Show the same files exist (because they're on the same branch, in this case)
Switch back and forth quickly to show they're in truly separate directories
Run git worktree list from the new worktree — it shows both worktrees

Step 5: Create a Second Worktree (45 seconds)

Go back to main: cd ../main-directory
Create another branch: git checkout -b feature/database
Create a worktree for it: git worktree add ../database-worktree feature/database
Run: git worktree list to show all three worktrees
Optionally, switch to ../database-worktree and show it's a different branch

Step 6: Show Shared Git History (30 seconds)

In any worktree, run: git log --oneline -3
Move to another worktree and run the same command
Point out: identical history, because they share .git

Code Examples & Commands

Creating Worktrees

# Create a worktree for an existing branch
git worktree add ../feature-a feature/auth-system

# Create a worktree with a new branch (shorter syntax)
git worktree add ../feature-b -b feature/database

# Create a worktree based on a remote branch
git worktree add ../feature-c origin/feature/payments

Listing and Managing Worktrees

# List all worktrees
git worktree list

# List with verbose output (shows branch and commit)
git worktree list --verbose

# Remove a worktree (only works if it's clean)
git worktree remove ../feature-a

# Remove a worktree forcefully (if it has uncommitted changes)
git worktree remove ../feature-a --force

# Repair worktree links (if directories are moved)
git worktree repair

Checking Worktree Status

# Inside a worktree, check what branch you're on
git branch

# See which worktree you're in (shows in git status output)
git status

# Confirm the shared .git by checking its location
git rev-parse --git-dir
# Output will show something like: /path/to/main/.git

Gotchas & Tips

Common Pitfalls

Both worktrees on the same branch: Don't check out the same branch in two worktrees. Git will prevent most operations, but it can cause confusion. Always create a separate branch per worktree.
Forgetting which directory you're in: Easy to edit files in the wrong worktree. Always check your current path with pwd or add the worktree name to your shell prompt.
Disk space grows quickly: Each worktree includes a full copy of the working files. A 2GB codebase × 5 worktrees = 10GB on disk. Be mindful of how many you create.
Stale worktree links: If you manually delete a worktree directory without using git worktree remove, the link persists. Use git worktree prune to clean up dead links, or git worktree repair if directories are moved.

Pro Tips

Add worktree name to your shell prompt so you always know which directory you're in
Use descriptive paths: ../feature-auth, ../bugfix-login, etc. beats ../worktree-1, ../worktree-2
Keep worktrees at the same level: All siblings of the main repo directory makes it easier to navigate (../auth, ../database, etc.)
Clean up when done: Run git worktree remove ../feature-a as soon as the work is merged and the worktree isn't needed

Lead-out

Now that you understand how worktrees work at the Git level, let's take the next step: running actual Claude Code sessions in parallel, one per worktree. In the next video, we'll set up multiple sessions with proper task assignment and coordination using tmux to manage them all on screen.

Reference URLs

Prep Reading

Skim the official Git worktrees docs (5 min) — focus on the "SYNOPSIS" and "DESCRIPTION" sections
Read any recent posts about parallel development workflows with AI agents
Review the git repository you'll use for the demo (make sure it has at least 3 commits and a few branches)

Notes for Daniel

The core concept here is simple but powerful: worktrees are just separate checked-out directories sharing one .git. Don't overcomplicate it. The demo should feel smooth and natural — show the commands, show the directories, move between them confidently. Viewers should walk away understanding that this is better than cloning multiple times, and ready to see how to run agents in these worktrees. This video sets up the foundation; keep it focused and clear.

When showing the .git sharing, you can briefly ls -la the .git directory or just mention it — don't spend time explaining Git internals. The point is: same Git database, separate file states.

Optional: Show a simple diagram on screen (text or simple slide graphic) showing: Main worktree + 2 feature worktrees all pointing to one .git box. This can help viewers visualize the architecture.

Quick Reference