asonas/git-worktree-workflow

Git Worktree Workflow

Leverage git-wt to create and manage Git Worktrees for parallel development environments.

Primary Use Cases

• Feature Development: Develop new features in isolated worktrees
• Bug Fixes: Fix urgent bugs without interrupting main development flow
• Experimental Work: Try new ideas without affecting the main branch
• Code Reviews: Create dedicated worktrees for PR reviews

Actions When Invoked

When this skill is activated, the following workflow will be executed:

1. Status Check

# List existing worktrees
git wt

2. Create Working Worktree

For Feature Development

# Create worktree for feature/feature-name
git wt feature/[feature-name]

# Create from specific branch
git wt feature/[feature-name] origin/main

For Bug Fixes

# Create worktree for hotfix/fix-description
git wt hotfix/[fix-description] origin/main

For Experimental Work

# Create worktree for experiment/experiment-name
git wt experiment/[experiment-name]

3. Switch Between Worktrees

# Switch to existing worktree
git wt [branch-name-or-worktree-name]

4. Cleanup After Work

If docker compose up was run inside the worktree, stop the containers first. Docker Compose uses the worktree directory name as the project name, so containers keep running and occupy ports even after you leave the worktree.

# Stop Docker Compose services started in the worktree
docker compose -p [worktree-dir-name] down

# Safely delete worktree and branch (only if merged)
git wt -d [branch-name]

# Force delete (with unmerged changes)
git wt -D [branch-name]

Recommended Workflows

TDD Development Workflow

1. Create Feature Worktree

   git wt feature/new-component
   

2. Test and Implementation

   • Red: Write failing test
   • Green: Minimal implementation to pass
   • Refactor: Improve code quality

3. Sync with Main Branch

   # Fetch latest from main
   git fetch origin
   git merge origin/main
   

4. Create and Merge PR

   • Create PR on GitHub
   • Merge after review

5. Cleanup Worktree

   # Stop Docker Compose services if started in the worktree
   docker compose -p [worktree-dir-name] down
   
   git wt -d feature/new-component
   

Parallel Work Example

# While working on feature/payment-integration

# 1. Create hotfix worktree without interrupting current work
git wt hotfix/critical-security-fix origin/main

# 2. Apply fix and push
git add .
git commit -m "Fix critical security vulnerability"
git push -u origin hotfix/critical-security-fix

# 3. Return to original work
git wt feature/payment-integration

# 4. Stop any Docker Compose services, then delete worktree
docker compose -p critical-security-fix down
git wt -d hotfix/critical-security-fix

Configuration Customization

Configure per-project settings:

# Set worktree base directory
git config wt.basedir "../{gitroot}-worktrees"

# Copy ignored files like .env
git config wt.copyignored true

# Install dependencies after creating worktree
git config --add wt.hook "npm install"
git config --add wt.hook "bundle install"

Best Practices

1. Consistent Naming Convention

   • feature/: New features
   • hotfix/: Emergency fixes
   • bugfix/: Regular bug fixes
   • experiment/: Experimental changes
   • chore/: Refactoring and maintenance

2. Regular Cleanup

   • Delete merged worktrees promptly
   • Check status regularly with git wt

3. Dependency Management

   • Keep node_modules independent per worktree
   • Auto-copy env files with wt.copyignored

4. Clear Context

   • Document what each worktree is for
   • Link to TODO lists or issue numbers

Troubleshooting

Cannot Delete Worktree

# Use force delete
git wt -D [branch-name]

# Manual deletion if needed
rm -rf ../[worktree-dir]
git worktree prune

Port Conflict from Orphaned Containers

If docker compose up fails with "port is already allocated", another worktree's containers may still be running:

# Find which compose project holds the port
docker ps --filter "publish=<port>" --format "table {{.Names}}\t{{.Ports}}"

# List all running compose projects
docker compose ls

# Stop the orphaned project
docker compose -p <project-name> down

Lost Worktree Location

# Show detailed worktree information
git worktree list --porcelain

Environment Files Not Copied

# Enable copying of gitignored files
git config wt.copyignored true