zhongwei/gh-cskiro-claudex

Fork 0

Files

Zhongwei Li f125e90b9f Initial commit

2025-11-29 18:16:40 +08:00

13 KiB

Raw Blame History

Git Worktree Best Practices

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

Branch Naming Conventions
Worktree Organization
Resource Management
Workflow Patterns
Cleanup Strategies
Team Collaboration
Performance Optimization
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:

Limit Active Worktrees
- Keep 3-5 active worktrees maximum
- Clean up merged branches weekly
- Archive instead of keeping indefinitely
Share When Possible
- Use pnpm for shared node_modules
- Enable yarn's zero-installs
- Share build caches

Clean Build Artifacts

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

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:

Use descriptive branch names - Future you will thank you
Keep worktrees organized - Consistent location pattern
Monitor disk space - Limit active worktrees
Clean up regularly - Don't hoard merged branches
Document team conventions - Everyone follows same patterns
Optimize for performance - Use pnpm, shared caches
Secure sensitive data - Clean .env before removal
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!

13 KiB Raw Blame History