6.6 KiB
6.6 KiB
Parallel Development with Git Worktrees
Overview
Git worktrees enable parallel development across multiple features without branch switching overhead. Each worktree is an independent working directory with its own:
- Branch checkout
- Virtual environment
- File modifications
- Development state
Worktree Structure
apps/
├── trax/ # Main repository (main branch)
└── trax-worktrees/ # Parallel development worktrees
├── trax-features/ # Feature development (feature/development)
├── trax-testing/ # Testing & QA (testing/qa)
├── trax-docs/ # Documentation (docs/updates)
├── trax-performance/ # Performance optimization (perf/optimization)
├── trax-bugfix/ # Bug fixes (fix/current)
├── switch.sh # Quick worktree switcher
└── status.sh # Status overview script
Quick Start
Setup Worktrees (One-Time)
cd apps/trax
.claude/scripts/setup_worktrees.sh
Check Status
# See all worktrees and their status
/Users/enias/projects/my-ai-projects/apps/trax-worktrees/status.sh
# Or use git directly
git worktree list
Switch Between Worktrees
# Interactive switcher
/Users/enias/projects/my-ai-projects/apps/trax-worktrees/switch.sh
# Or navigate directly
cd ../trax-worktrees/trax-features
source .venv/bin/activate
Multi-Claude Workflow
Open separate Claude Code sessions for parallel work:
Terminal 1: Feature Development
cd apps/trax-worktrees/trax-features
source .venv/bin/activate
claude
# Work on new features
Terminal 2: Testing
cd apps/trax-worktrees/trax-testing
source .venv/bin/activate
claude
# Write and run tests
Terminal 3: Documentation
cd apps/trax-worktrees/trax-docs
source .venv/bin/activate
claude
# Update documentation
Workflow Patterns
1. Feature Development Pattern
# In trax-features worktree
git checkout -b feature/whisper-integration
# Implement feature
git add .
git commit -m "feat: add Whisper transcription service"
git push origin feature/whisper-integration
# Create PR on Gitea
2. Bug Fix Pattern
# In trax-bugfix worktree
git checkout -b fix/memory-leak
# Fix bug
git add .
git commit -m "fix: resolve memory leak in batch processor"
git push origin fix/memory-leak
# Create PR for quick merge
3. Testing Pattern
# In trax-testing worktree
# Pull latest changes from feature branch
git fetch origin
git checkout feature/whisper-integration
# Write comprehensive tests
uv run pytest tests/ -v
# Push test improvements
git push origin feature/whisper-integration
4. Documentation Pattern
# In trax-docs worktree
# Update docs for new features
git checkout -b docs/whisper-api
# Update documentation
git add docs/
git commit -m "docs: add Whisper API documentation"
git push origin docs/whisper-api
Best Practices
1. Branch Naming Convention
- Features:
feature/description - Fixes:
fix/issue-description - Docs:
docs/what-updated - Performance:
perf/optimization-target - Testing:
test/what-testing
2. Worktree Hygiene
# Clean up finished worktrees
git worktree remove ../trax-worktrees/trax-features
# Prune stale worktree info
git worktree prune
# Re-create if needed
git worktree add ../trax-worktrees/trax-features feature/new-work
3. Syncing Changes
# In any worktree, pull latest main
git fetch origin
git merge origin/main
# Or rebase for cleaner history
git rebase origin/main
4. Virtual Environment Management
Each worktree has its own .venv:
# Activate worktree's venv
source .venv/bin/activate
# Install new dependencies
uv pip install package-name
# Sync with pyproject.toml
uv pip install -e ".[dev]"
Common Commands
Worktree Management
# List all worktrees
git worktree list
# Add new worktree
git worktree add ../trax-worktrees/trax-experimental experimental/ai-agents
# Remove worktree
git worktree remove ../trax-worktrees/trax-experimental
# Clean up
git worktree prune
Branch Operations
# Push new branch to remote
git push -u origin branch-name
# Delete remote branch after merge
git push origin --delete branch-name
# Clean up local branches
git branch -d branch-name
Integration with Gitea
Creating Pull Requests
# After pushing branch
gh pr create --title "Feature: Description" --body "Details"
# Or use Gitea web UI
open https://eniasgit.zeabur.app/demo/trax
CI/CD Triggers
Each worktree push triggers Gitea workflows:
- Linting and formatting checks
- Test suite execution
- Type checking
- Build validation
Troubleshooting
Issue: Worktree locked
# Remove lock file
rm .git/worktrees/*/locked
# Or force remove
git worktree remove --force <path>
Issue: Branch conflicts
# In worktree with conflicts
git fetch origin
git rebase origin/main
# Resolve conflicts
git rebase --continue
Issue: Venv issues
# Recreate virtual environment
rm -rf .venv
python3.11 -m venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
Advanced Patterns
1. Experimental Features
Create isolated worktree for experiments:
git worktree add ../trax-experiment experimental/crazy-idea
cd ../trax-experiment
# Experiment freely without affecting other work
2. Release Preparation
Dedicated worktree for releases:
git worktree add ../trax-release release/v1.0.0
cd ../trax-release
# Prepare release: version bumps, changelog, etc.
3. Hotfix Workflow
Quick fixes on production:
git worktree add ../trax-hotfix main
cd ../trax-hotfix
git checkout -b hotfix/critical-bug
# Fix and push immediately
Performance Benefits
- No context switching: Each worktree maintains its state
- Parallel testing: Run tests in one worktree while developing in another
- Instant branch access: No need to stash/commit to switch branches
- Independent dependencies: Each worktree can have different package versions
- Multiple Claude sessions: Each worktree can have its own Claude Code instance
Summary
Git worktrees provide a powerful parallel development environment:
- 🚀 5 default worktrees for common workflows
- 🔧 Convenience scripts for management
- 🐍 Independent Python environments per worktree
- 📝 Clear branch organization by purpose
- 🤖 Multi-Claude capability for parallel AI assistance
Use worktrees to maintain development velocity while keeping clean separation between different work streams.