gh-cskiro-claudex-devops-tools/skills/git-worktree-setup/data/best-practices.md

Git Worktree Best Practices

A comprehensive guide to using git worktrees effectively for parallel development with Claude Code.

Table of Contents

1. Branch Naming Conventions
2. Worktree Organization
3. Resource Management
4. Workflow Patterns
5. Cleanup Strategies
6. Team Collaboration
7. Performance Optimization
8. Security Considerations

---

Branch Naming Conventions

Recommended Patterns

Feature Branches:

feature/descriptive-name
feature/user-authentication
feature/payment-integration
feature/dashboard-redesign

Bugfix Branches:

bugfix/issue-number-description
bugfix/123-login-redirect
bugfix/456-memory-leak
bugfix/789-validation-error

Hotfix Branches:

hotfix/critical-issue
hotfix/security-patch
hotfix/production-crash

Experimental Branches:

experiment/idea-name
experiment/new-architecture
experiment/performance-test

Chore Branches:

chore/dependency-updates
chore/refactor-auth
chore/update-docs

Why Good Names Matter

• Clarity: Instantly understand the purpose
• Organization: Easy to group and filter
• Cleanup: Identify old branches quickly
• Collaboration: Team members know what's being worked on

Naming Anti-Patterns

❌ Avoid:

• Vague names: fix, update, changes
• Personal names: johns-branch, temp-work
• Dates only: 2025-09-04, sept-changes
• No context: test, wip, tmp

✅ Use:

• Descriptive: feature/oauth-integration
• Issue-linked: bugfix/1234-payment-error
• Purpose-clear: experiment/graphql-migration

---

Worktree Organization

Directory Structure

Recommended: Sibling Directories

~/projects/
├── myapp/                    # Main worktree
├── myapp-feature-auth/       # Feature worktree
├── myapp-bugfix-login/       # Bugfix worktree
└── myapp-experiment-ui/      # Experiment worktree

Alternative: Dedicated Worktrees Directory

~/projects/
├── myapp/                    # Main worktree
└── myapp-worktrees/          # All worktrees
    ├── feature-auth/
    ├── bugfix-login/
    └── experiment-ui/

Team Shared Setup:

~/work/
├── myapp/                    # Main (stable)
├── myapp-review/             # For PR reviews
├── myapp-hotfix/             # Emergency fixes
└── myapp-current/            # Active feature work

Location Best Practices

✅ Do:

• Keep worktrees near main repo (faster operations)
• Use consistent naming pattern
• Group by purpose if many worktrees
• Document custom locations in team wiki

❌ Don't:

• Scatter worktrees across filesystem
• Use deep nested paths (slow operations)
• Mix worktrees with unrelated projects
• Create worktrees inside other worktrees

---

Resource Management

Disk Space

Understanding Space Usage:

Main repository: 150 MB
Each worktree:
  - Repository files: 150 MB
  - node_modules: 700 MB
  - Build artifacts: 50 MB
  Total: ~900 MB per worktree

Space Management Strategies:

1. Limit Active Worktrees

   • Keep 3-5 active worktrees maximum
   • Clean up merged branches weekly
   • Archive instead of keeping indefinitely

2. Share When Possible

   • Use pnpm for shared node_modules
   • Enable yarn's zero-installs
   • Share build caches

3. Clean Build Artifacts

   # Clean before removing worktree
   cd worktree-path
   npm run clean
   rm -rf dist/ build/ .next/
   

4. Monitor Disk Usage

   # Check worktree sizes
   du -sh ../myapp-*
   
   # Find largest directories
   du -sh */ | sort -hr | head -10
   

Memory Considerations

Running Multiple Claude Code Sessions:

• Each session: ~500MB RAM
• 3 parallel sessions: ~1.5GB RAM
• Keep system RAM usage < 80%

Tips:

• Close unused sessions
• Restart sessions periodically
• Use /handoff to preserve context
• Monitor system performance

CPU Management

Avoid Parallel Builds:

# Bad: Running builds in all worktrees simultaneously
cd worktree1 && npm run build &
cd worktree2 && npm run build &
cd worktree3 && npm run build &

# Good: Sequential or limited parallel
npm run build  # One at a time

Use Build Queues:

• Serialize resource-intensive operations
• Limit concurrent processes
• Use tools like make -j2 for controlled parallelism

---

Workflow Patterns

Pattern 1: Feature Development

1. Create worktree for feature
   └─ git worktree add ../myapp-feature-x -b feature-x

2. Develop in isolation
   └─ cd ../myapp-feature-x && claude

3. Test independently
   └─ npm test && npm run build

4. Merge when ready
   └─ git checkout main && git merge feature-x

5. Clean up
   └─ git worktree remove ../myapp-feature-x

Pattern 2: PR Review

1. Create worktree from PR branch
   └─ git worktree add ../myapp-review pr-branch

2. Review code with Claude Code
   └─ cd ../myapp-review && claude

3. Test changes
   └─ npm install && npm test

4. Leave feedback
   └─ (Review in Claude Code)

5. Remove when done
   └─ git worktree remove ../myapp-review

Pattern 3: Hotfix While Developing

Current state: Working on feature-x in worktree

1. Create hotfix worktree from main
   └─ git worktree add ../myapp-hotfix -b hotfix-critical

2. Fix issue in hotfix worktree
   └─ cd ../myapp-hotfix && claude

3. Test and deploy
   └─ npm test && deploy

4. Continue feature work
   └─ cd ../myapp-feature-x

5. Merge hotfix to both main and feature
   └─ git checkout feature-x && git merge main

Pattern 4: Integration Testing

1. Create worktrees for all features
   └─ Batch create: feature-a, feature-b, feature-c

2. Test each independently
   └─ Parallel Claude Code sessions

3. Create integration worktree
   └─ git worktree add ../myapp-integration -b integration

4. Merge all features to integration
   └─ git merge feature-a feature-b feature-c

5. Test combined functionality
   └─ npm test && npm run e2e

6. Clean up all worktrees after merge

Pattern 5: Comparison Testing

1. Keep main worktree as baseline
2. Create feature worktree for new implementation
3. Run same tests in both
4. Compare results side-by-side
5. Make decision based on data

---

Cleanup Strategies

Daily Cleanup

Check merged branches:

# List merged branches
git branch --merged main | grep -v "main"

# Remove worktrees for merged branches
for branch in $(git branch --merged main | grep -v "main"); do
  git worktree remove ../myapp-$branch 2>/dev/null || true
  git branch -d $branch
done

Weekly Cleanup

Review all worktrees:

# List all worktrees with age
git worktree list | while read path commit branch; do
  cd "$path"
  age=$(git log -1 --format=%ar)
  echo "$branch: last activity $age"
done

Remove stale worktrees (30+ days):

# Manual review first, then remove
git worktree list | grep -v main | while read path; do
  cd "$path"
  last_commit=$(git log -1 --format=%ct)
  current_time=$(date +%s)
  days_old=$(( (current_time - last_commit) / 86400 ))

  if [ $days_old -gt 30 ]; then
    echo "Stale: $path ($days_old days old)"
  fi
done

Automated Cleanup

Git hooks for cleanup:

# .git/hooks/post-merge
#!/bin/bash
# Auto-cleanup merged branches

CURRENT_BRANCH=$(git branch --show-current)

if [ "$CURRENT_BRANCH" = "main" ]; then
  echo "Checking for merged worktrees..."

  git branch --merged main | grep -v "main" | while read branch; do
    # Check if worktree exists
    if git worktree list | grep -q "\\[$branch\\]"; then
      echo "Found merged worktree: $branch"
      echo "Run: git worktree remove /path/to/$branch"
    fi
  done
fi

Cleanup Checklist

Before removing a worktree:

• No uncommitted changes
• Branch merged or backed up
• No important local files
• Dependencies can be reinstalled
• No running processes

---

Team Collaboration

Shared Worktree Conventions

Team Standards Document:

# Worktree Standards

## Naming
- Features: feature/{jira-id}-{description}
- Bugfixes: bugfix/{issue-id}-{description}
- Reviews: review-{pr-number}

## Location
- All worktrees in ~/projects/myapp-worktrees/

## Lifecycle
- Create: Before starting work
- Update: Sync with main daily
- Remove: Within 24h of merge

## Resources
- Max 3 active worktrees per developer
- Clean up merged branches in daily standup

Communication

Notify team of worktrees:

# In team chat
Working on worktrees:
- feature-auth (for AUTH-123)
- bugfix-login (for BUG-456)
- review-pr-789 (reviewing Sarah's PR)

Will clean up by EOD.

Shared Scripts

Team cleanup script:

#!/bin/bash
# team-worktree-status.sh

echo "Worktree Status for $(whoami)"
echo "================================"

git worktree list | while read path commit branch; do
  cd "$path"
  status=$(git status --porcelain | wc -l)
  behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo "N/A")

  echo "$branch:"
  echo "  Changes: $status"
  echo "  Behind main: $behind"
  echo "  Path: $path"
  echo ""
done

---

Performance Optimization

Git Operations

Fetch Once, Use Everywhere:

# In main worktree
git fetch --all

# All worktrees automatically have access
# No need to fetch in each worktree

Shallow Clones for Reviews:

# For temporary review worktrees
git worktree add --detach ../review-pr HEAD
cd ../review-pr
git fetch origin pull/123/head:pr-123
git checkout pr-123

Build Performance

Share Build Caches:

# In main repo
export TURBO_CACHE_DIR=/shared/turbo-cache

# All worktrees use same cache
# Builds are faster after first run

Incremental Builds:

# Don't clean between branches
npm run build  # Uses previous cache

# Only clean when needed
npm run clean && npm run build

Dependency Management

pnpm (Recommended for Worktrees):

# Global store, minimal duplication
pnpm install

# All worktrees reference same packages
# Saves ~80% disk space

npm/yarn (Standard):

# Each worktree has full node_modules
# More disk space, complete isolation
npm install

---

Security Considerations

Environment Variables

Never commit .env:

# Each worktree needs own .env
cp ../.env .env

# Add to .gitignore (should already be there)
echo ".env" >> .gitignore

Worktree-specific configs:

# Different API endpoints per worktree
# main: production API
# feature-x: staging API
# experiment: local API

# .env in each worktree
API_URL=https://staging.api.example.com

Credentials

Don't share credentials between worktrees:

• Separate SSH keys if needed
• Different tokens per environment
• Revoke credentials in removed worktrees

Clean credentials before removal:

# Before removing worktree
cd worktree-path
rm -f .env .env.local
rm -f config/credentials.json

# Then remove
git worktree remove $(pwd)

Access Control

Workspace Permissions:

# Ensure proper permissions
chmod 700 ~/projects/myapp-*

# No group/other access to sensitive worktrees

---

Advanced Tips

Worktree Templates

Quick setup script:

#!/bin/bash
# new-worktree.sh

BRANCH=$1
PATH=../myapp-$BRANCH

git worktree add $PATH -b $BRANCH
cd $PATH
cp ../.env .
pnpm install
code .  # Open in editor

echo "Worktree ready: $PATH"

Automation

Auto-sync worktrees:

# cron job: daily sync
0 9 * * * cd ~/projects/myapp && git fetch && \
  for wt in $(git worktree list | awk '{print $1}'); do \
    cd $wt && git pull --rebase 2>/dev/null; \
  done

Monitoring

Disk space alerts:

# Alert when worktrees exceed threshold
TOTAL=$(du -sm ~/projects/myapp-* | awk '{sum+=$1} END {print sum}')

if [ $TOTAL -gt 10000 ]; then
  echo "Warning: Worktrees using ${TOTAL}MB"
fi

---

Quick Reference

Commands

# Create
git worktree add ../myapp-branch -b branch

# List
git worktree list

# Remove
git worktree remove ../myapp-branch

# Prune orphaned
git worktree prune

# Repair if corrupted
git worktree repair

# Move worktree
git worktree move old-path new-path

# Lock (prevent removal)
git worktree lock path

# Unlock
git worktree unlock path

Aliases

# Add to ~/.gitconfig
[alias]
  wt = worktree
  wtl = worktree list
  wta = "!f() { git worktree add ../$(basename $(pwd))-$1 -b $1; }; f"
  wtr = worktree remove
  wtp = worktree prune

Usage:

git wta feature-x          # Creates ../myapp-feature-x
git wtl                    # Lists all worktrees
git wtr ../myapp-feature-x # Removes worktree

---

Summary

Key Takeaways:

1. Use descriptive branch names - Future you will thank you
2. Keep worktrees organized - Consistent location pattern
3. Monitor disk space - Limit active worktrees
4. Clean up regularly - Don't hoard merged branches
5. Document team conventions - Everyone follows same patterns
6. Optimize for performance - Use pnpm, shared caches
7. Secure sensitive data - Clean .env before removal
8. Automate repetitive tasks - Scripts for common operations

Remember: Git worktrees are powerful tools for parallel development. Used well, they enhance productivity. Used poorly, they create chaos. Follow these best practices for worktree success!