canvas-website/WORKTREE_SETUP.md

Git Worktree Automation Setup

This repository is configured to automatically create Git worktrees for new branches, allowing you to work on multiple branches simultaneously without switching contexts.

What Are Worktrees?

Git worktrees allow you to have multiple working directories (copies of your repo) checked out to different branches at the same time. This means:

• No need to stash or commit work when switching branches
• Run dev servers on multiple branches simultaneously
• Compare code across branches easily
• Keep your main branch clean while working on features

Automatic Worktree Creation

A Git hook (.git/hooks/post-checkout) is installed that automatically creates worktrees when you create a new branch from main:

# This will automatically create a worktree at ../canvas-website-feature-name
git checkout -b feature/new-feature

Worktree Location Pattern:

/home/jeffe/Github/
├── canvas-website/                    # Main repo (main branch)
├── canvas-website-feature-name/       # Worktree for feature branch
└── canvas-website-bugfix-something/   # Worktree for bugfix branch

Manual Worktree Management

Use the worktree-manager.sh script for manual management:

List All Worktrees

./scripts/worktree-manager.sh list

Create a New Worktree

# Creates worktree for existing branch
./scripts/worktree-manager.sh create feature/my-feature

# Or create new branch with worktree
./scripts/worktree-manager.sh create feature/new-branch

Remove a Worktree

./scripts/worktree-manager.sh remove feature/old-feature

Clean Up All Worktrees (Keep Main)

./scripts/worktree-manager.sh clean

Show Status of All Worktrees

./scripts/worktree-manager.sh status

Navigate to a Worktree

# Get worktree path
./scripts/worktree-manager.sh goto feature/my-feature

# Or use with cd
cd $(./scripts/worktree-manager.sh goto feature/my-feature)

Help

./scripts/worktree-manager.sh help

Workflow Examples

Starting a New Feature

With automatic worktree creation:

# In main repo
cd /home/jeffe/Github/canvas-website

# Create and switch to new branch (worktree auto-created)
git checkout -b feature/terminal-tool

# Notification appears:
# 🌳 Creating worktree for branch: feature/terminal-tool
# 📁 Location: /home/jeffe/Github/canvas-website-feature-terminal-tool

# Continue working in current directory or switch to worktree
cd ../canvas-website-feature-terminal-tool

Manual worktree creation:

./scripts/worktree-manager.sh create feature/my-feature
cd $(./scripts/worktree-manager.sh goto feature/my-feature)

Working on Multiple Features Simultaneously

# Terminal 1: Main repo (main branch)
cd /home/jeffe/Github/canvas-website
npm run dev  # Port 5173

# Terminal 2: Feature branch 1
cd /home/jeffe/Github/canvas-website-feature-auth
npm run dev  # Different port

# Terminal 3: Feature branch 2
cd /home/jeffe/Github/canvas-website-feature-ui
npm run dev  # Another port

# All running simultaneously, no conflicts!

Comparing Code Across Branches

# Use diff or your IDE to compare files
diff /home/jeffe/Github/canvas-website/src/App.tsx \
     /home/jeffe/Github/canvas-website-feature-auth/src/App.tsx

# Or open both in VS Code
code /home/jeffe/Github/canvas-website \
     /home/jeffe/Github/canvas-website-feature-auth

Cleaning Up After Merging

# After merging feature/my-feature to main
cd /home/jeffe/Github/canvas-website

# Remove the worktree
./scripts/worktree-manager.sh remove feature/my-feature

# Or clean all worktrees except main
./scripts/worktree-manager.sh clean

How It Works

Post-Checkout Hook

The .git/hooks/post-checkout script runs automatically after git checkout and:

1. Detects if you're creating a new branch from main
2. Creates a worktree in ../canvas-website-{branch-name}
3. Links the worktree to the new branch
4. Shows a notification with the worktree path

Hook Behavior:

• ✅ Creates worktree when: git checkout -b new-branch (from main)
• ❌ Skips creation when:
  • Switching to existing branches
  • Already in a worktree
  • Worktree already exists for that branch
  • Not branching from main/master

Worktree Manager Script

The scripts/worktree-manager.sh script provides:

• User-friendly commands for worktree operations
• Colored output for better readability
• Error handling and validation
• Status reporting across all worktrees

Git Commands with Worktrees

Most Git commands work the same way in worktrees:

# In any worktree
git status           # Shows status of current worktree
git add .            # Stages files in current worktree
git commit -m "..."  # Commits in current branch
git push             # Pushes current branch
git pull             # Pulls current branch

# List all worktrees (works from any worktree)
git worktree list

# Remove a worktree (from main repo)
git worktree remove feature/branch-name

# Prune deleted worktrees
git worktree prune

Important Notes

Shared Git Directory

All worktrees share the same .git directory (in the main repo), which means:

• ✅ Commits, branches, and remotes are shared across all worktrees
• ✅ One git fetch or git pull in main updates all worktrees
• ⚠️ Don't delete the main repo while worktrees exist
• ⚠️ Stashes are shared (stash in one worktree, pop in another)

Node Modules

Each worktree has its own node_modules:

• First time entering a worktree: run npm install
• Dependencies may differ across branches
• More disk space usage (one node_modules per worktree)

Port Conflicts

When running dev servers in multiple worktrees:

# Main repo
npm run dev  # Uses default port 5173

# In worktree, specify different port
npm run dev -- --port 5174

IDE Integration

VS Code:

# Open specific worktree
code /home/jeffe/Github/canvas-website-feature-name

# Or open multiple worktrees as workspace
code --add /home/jeffe/Github/canvas-website \
     --add /home/jeffe/Github/canvas-website-feature-name

Troubleshooting

Worktree Path Already Exists

If you see:

fatal: '/path/to/worktree' already exists

Remove the directory manually:

rm -rf /home/jeffe/Github/canvas-website-feature-name
git worktree prune

Can't Delete Main Repo

If you have active worktrees, you can't delete the main repo. Clean up first:

./scripts/worktree-manager.sh clean

Worktree Out of Sync

If a worktree seems out of sync:

cd /path/to/worktree
git fetch origin
git reset --hard origin/branch-name

Hook Not Running

If the post-checkout hook isn't running:

# Check if it's executable
ls -la .git/hooks/post-checkout

# Make it executable if needed
chmod +x .git/hooks/post-checkout

# Test the hook manually
.git/hooks/post-checkout HEAD HEAD 1

Disabling Automatic Worktrees

To disable automatic worktree creation:

# Remove or rename the hook
mv .git/hooks/post-checkout .git/hooks/post-checkout.disabled

To re-enable:

mv .git/hooks/post-checkout.disabled .git/hooks/post-checkout

Advanced Usage

Custom Worktree Location

Modify the post-checkout hook to change the worktree location:

# Edit .git/hooks/post-checkout
# Change this line:
WORKTREE_BASE=$(dirname "$REPO_ROOT")

# To (example):
WORKTREE_BASE="$HOME/worktrees"

Worktree for Remote Branches

# Create worktree for remote branch
git worktree add ../canvas-website-remote-branch origin/feature-branch

# Or use the script
./scripts/worktree-manager.sh create origin/feature-branch

Detached HEAD Worktree

# Create worktree at specific commit
git worktree add ../canvas-website-commit-abc123 abc123

Best Practices

1. Clean up regularly: Remove worktrees for merged branches
2. Name branches clearly: Worktree names mirror branch names
3. Run npm install: Always run in new worktrees
4. Check branch: Always verify which branch you're on before committing
5. Use status command: Check all worktrees before major operations

Resources

• Git Worktree Documentation
• Git Hooks Documentation

---

Setup Complete! New branches will automatically create worktrees. Use ./scripts/worktree-manager.sh help for manual management.