Worktree Management

Advanced Git worktree techniques for multi-agent development

Worktree Management

Master Git worktrees for efficient multi-agent development.

Git Worktrees Explained

Git worktrees allow multiple working directories to be attached to a single repository.

Key Benefits:

  • Share Git history (no duplication)
  • Independent working directories
  • Separate branches
  • Fast switching between features

Creating Worktrees

Basic Creation

# Create worktree for new branch
git worktree add -b feature/auth worktrees/agent-1 develop

# Create worktree from existing branch
git worktree add worktrees/agent-2 feature/existing

# List all worktrees
git worktree list

Using Scripts

# Automated setup
.\scripts\agent-management\setup-agent-development.ps1 `
  -AgentName "agent-1" `
  -BaseBranch "develop" `
  -FeatureName "authentication"

Worktree Structure

portfolio-os/
├── .git/                      # Shared Git database
├── apps/                      # Main worktree
├── packages/
├── worktrees/
│   ├── agent-1-chris/        # Agent 1 worktree
│   │   ├── apps/
│   │   ├── packages/
│   │   └── .git              # Link to main .git
│   ├── agent-2-jason/        # Agent 2 worktree
│   │   ├── apps/
│   │   ├── packages/
│   │   └── .git              # Link to main .git
│   └── agent-3-alex/         # Agent 3 worktree

Naming Conventions

PatternExampleUse Case
agent-N-nameagent-1-chrisAgent-specific work
feature-namefeature-authFeature development
fix-issue-Nfix-issue-123Bug fixes
experiment-nameexperiment-new-uiExperimental work

Managing Worktrees

Common Operations

# Create new worktree
git worktree add -b feature/new-feature worktrees/new-feature develop

# Navigate to worktree
cd worktrees/new-feature

# Install dependencies
pnpm install

# Start working
pnpm dev

Syncing with Develop

Keep worktrees updated with develop branch:

# In worktree
git fetch origin develop
git rebase develop

# Handle conflicts if any
git rebase --continue  # after resolving

# Or abort if needed
git rebase --abort

Worktree Lifecycle

1

Creation

Create worktree for specific task:

git worktree add -b feature/task worktrees/task develop
2

Development

Work in isolation:

cd worktrees/task
# Make changes
git commit -m "feat: implement task"
3

Push & PR

Push and create PR:

git push origin feature/task
# Create PR via GitHub or script
4

Cleanup

After PR merged:

cd ../..
git worktree remove worktrees/task
git branch -d feature/task

Advanced Techniques

Sharing Node Modules

Symlink to save disk space:

# In main repo
pnpm install

# In worktree (careful!)
cd worktrees/agent-1
rm -rf node_modules
ln -s ../../node_modules node_modules

Note:

Warning: Shared node_modules can cause issues if dependencies differ between branches.

Sparse Worktrees

Only checkout specific directories:

# Create sparse worktree
git worktree add --no-checkout worktrees/docs-only develop
cd worktrees/docs-only
git sparse-checkout init --cone
git sparse-checkout set apps/docs
git checkout

Worktree Templates

Create template for consistent setup:

# setup-worktree-template.sh
git worktree add -b $BRANCH $PATH develop
cd $PATH
pnpm install
cp ../../.env.example .env.local
git config --local user.name "$AGENT_NAME"
git config --local user.email "$AGENT_EMAIL"

Troubleshooting

Worktree Locked

# Error: worktree is locked
Solution:
git worktree unlock worktrees/agent-1

Cannot Remove Worktree

# Error: worktree contains modifications
Solution:
cd worktrees/agent-1
git stash
cd ../..
git worktree remove worktrees/agent-1

Branch Already Exists

# Error: branch 'feature/x' already exists
Solution:
git worktree add worktrees/agent-1 existing-branch  # Use existing
# Or delete old branch first
git branch -D feature/x
git worktree add -b feature/x worktrees/agent-1 develop

Performance Issues

# Slow operations
Solution:
# Prune old worktree references
git worktree prune

# Clean up
git gc

Best Practices

Note:

Worktree Best Practices:

  1. One task per worktree - Keep focused
  2. Regular cleanup - Remove unused worktrees
  3. Meaningful names - Easy to identify
  4. Sync frequently - Rebase on develop daily
  5. Independent deps - Don't share node_modules
  6. Backup work - Push branches regularly

Automation Scripts

Portfolio OS includes worktree management scripts:

# Create agent worktree
.\scripts\agent-management\setup-agent-development.ps1 `
  -AgentName "agent-1"

# List all worktrees
.\scripts\agent-management\manage-worktree-operations-unified.ps1 `
  -Action list

# Sync worktree with develop
.\scripts\agent-management\manage-worktree-operations-unified.ps1 `
  -Action sync `
  -WorktreePath "worktrees/agent-1"

# Clean up old worktrees
.\scripts\agent-management\manage-worktree-operations-unified.ps1 `
  -Action cleanup

Monitoring Worktrees

Track worktree health:

# Check worktree status
git worktree list --porcelain

# View worktree state
Get-Content scripts/configuration/worktree-state.json | ConvertFrom-Json

# Generate worktree report
.\scripts\monitoring\worktree-health-check.ps1

Next Steps