git-workshop/02_advanced/03-worktrees/README.md

Module 13: Worktrees

Learning Objectives

By the end of this module, you will:

• Understand what Git worktrees are and when to use them
• Create and manage multiple working directories for the same repository
• Work on multiple branches simultaneously
• Understand the benefits of worktrees over stashing or cloning
• Remove and clean up worktrees

Challenge Description

You're working on a feature when an urgent bug report comes in. Instead of stashing your work or creating a separate clone, you'll use Git worktrees to work on both the feature and the bugfix simultaneously in different directories.

Your task is to:

1. Create a worktree for the bugfix on a separate branch
2. Fix the bug in the worktree
3. Commit and verify the fix
4. Continue working on your feature in the main working directory
5. Clean up the worktree when done

Key Concepts

What are Git Worktrees?

A worktree is an additional working directory attached to the same repository. Each worktree can have a different branch checked out, allowing you to work on multiple branches simultaneously without switching.

Traditional Workflow vs Worktrees

Traditional (switching branches):

main-repo/
  - Switch to bugfix branch
  - Fix bug
  - Switch back to feature branch
  - Continue feature work
  - (Requires stashing or committing incomplete work)

With Worktrees:

main-repo/           <- feature branch
worktrees/bugfix/    <- bugfix branch

Work in both simultaneously!

Why Use Worktrees?

Advantages:

• Work on multiple branches at the same time
• No need to stash or commit incomplete work
• Each worktree has its own working directory and index
• Share the same Git history (one .git directory)
• Faster than cloning the entire repository
• Perfect for code reviews, comparisons, or parallel development

Use Cases:

• Urgent bug fixes while working on a feature
• Code reviews (checkout PR in separate worktree)
• Comparing implementations side by side
• Running tests on one branch while coding on another
• Building different versions simultaneously

Useful Commands

# List all worktrees
git worktree list

# Add a new worktree
git worktree add <path> <branch>
git worktree add ../bugfix bugfix-branch

# Create new branch in worktree
git worktree add <path> -b <new-branch>
git worktree add ../feature-new -b feature-new

# Remove a worktree
git worktree remove <path>
git worktree remove ../bugfix

# Prune stale worktree information
git worktree prune

# Move a worktree
git worktree move <old-path> <new-path>

# Lock a worktree (prevent deletion)
git worktree lock <path>
git worktree unlock <path>

Verification

Run the verification script to check your solution:

.\verify.ps1

The verification will check that:

• You created a worktree for the bugfix
• The bug was fixed and committed in the worktree
• Your feature work continued in the main directory
• Both branches have the expected changes

Challenge Steps

1. Navigate to the challenge directory
2. You're in main-repo with a feature branch checked out
3. View current worktrees: git worktree list
4. Create a worktree for bugfix: git worktree add ../bugfix-worktree -b bugfix
5. Navigate to the worktree: cd ../bugfix-worktree
6. Fix the bug in calculator.js (fix the divide by zero check)
7. Commit the fix: git add . && git commit -m "Fix divide by zero bug"
8. Go back to main repo: cd ../main-repo
9. Continue working on your feature
10. Add a new method to calculator.js
11. Commit your feature
12. List worktrees: git worktree list
13. Remove the worktree: git worktree remove ../bugfix-worktree
14. Run verification

Tips

• Worktree paths are typically siblings of your main repo (use ../worktree-name)
• Each worktree must have a different branch checked out
• Can't checkout the same branch in multiple worktrees
• The main .git directory is shared, so commits in any worktree are visible everywhere
• Worktrees are listed in .git/worktrees/
• Use git worktree remove to clean up, or just delete the directory and run git worktree prune
• Worktrees persist across restarts until explicitly removed

Common Worktree Workflows

Urgent Bugfix

# Currently on feature branch with uncommitted changes
git worktree add ../hotfix -b hotfix

cd ../hotfix
# Fix the bug
git add .
git commit -m "Fix critical bug"
git push origin hotfix

cd ../main-repo
# Continue working on feature

Code Review

# Review a pull request without switching branches
git fetch origin pull/123/head:pr-123
git worktree add ../review-pr-123 pr-123

cd ../review-pr-123
# Review code, test it
# Run: npm test, npm start, etc.

cd ../main-repo
git worktree remove ../review-pr-123

Parallel Development

# Work on two features simultaneously
git worktree add ../feature-a -b feature-a
git worktree add ../feature-b -b feature-b

# Terminal 1
cd feature-a && code .

# Terminal 2
cd feature-b && code .

Build Comparison

# Compare builds between branches
git worktree add ../release-build release-v2.0

cd ../release-build
npm run build
# Test production build

# Meanwhile, continue development in main repo

Worktree vs Other Approaches

vs Stashing

• Stash: Temporary, one at a time, requires branch switching
• Worktree: Persistent, multiple simultaneously, no switching

vs Cloning

• Clone: Full copy, separate .git, uses more disk space
• Worktree: Shared .git, less disk space, instant sync

vs Branch Switching

• Switching: Requires clean working directory, one branch at a time
• Worktree: Keep dirty working directory, multiple branches active

What You'll Learn

Git worktrees are a powerful but underutilized feature that can significantly improve your workflow. They eliminate the need for constant branch switching, stashing, or maintaining multiple clones. Whether you're handling urgent fixes, reviewing code, or comparing implementations, worktrees provide a clean and efficient solution. Once you understand worktrees, you'll find many situations where they're the perfect tool for the job.