worktree-switch
Switch between git worktrees for parallel development. Use when working on multiple issues simultaneously.
When & Why to Use This Skill
The Worktree Switch skill enables developers to seamlessly navigate between isolated Git worktree directories, facilitating efficient parallel development. By eliminating the need for stashing or frequent branch switching, it streamlines context switching across multiple issues and enhances workflow productivity through organized, side-by-side environment management.
Use Cases
- Simultaneous Issue Management: Work on multiple feature branches or bug fixes concurrently without the overhead of constant branch switching.
- Zero-Stash Context Switching: Move between different project states instantly without needing to stash uncommitted changes or risk losing work-in-progress.
- Side-by-Side Implementation Comparison: Open and test different branches in separate directories to compare code logic or UI changes in real-time.
- Isolated Testing Environments: Maintain dedicated worktrees for specific testing scenarios to ensure environment consistency across different versions of the codebase.
| name | worktree-switch |
|---|---|
| description | "Switch between git worktrees for parallel development. Use when working on multiple issues simultaneously." |
| mcp_fallback | none |
| category | worktree |
Worktree Switch
Navigate between isolated worktree directories quickly.
When to Use
- Working on multiple issues
- Need to context switch without stashing
- Testing different branches side-by-side
- Comparing implementations
Quick Reference
# List all worktrees
git worktree list
# Switch worktree (simple cd)
cd ../ProjectOdyssey-42-feature
# Verify current worktree
git worktree list | grep "*"
# Switch by issue number (script)
./scripts/switch_worktree.sh 42
Workflow
- List worktrees - See all available worktrees and their paths
- Navigate -
cdto desired worktree directory - Verify - Check
git branchto confirm you're on right branch - Work - Make changes, commit normally
- Switch - Move to different worktree with simple
cd
Common Patterns
Terminal Aliases
# Add to ~/.bashrc or ~/.zshrc
alias wt='git worktree list'
alias wtcd='cd $(git worktree list | fzf | awk "{print \$1}")'
Tmux Sessions
# Create persistent session per worktree
tmux new -s issue-42 -c ../ProjectOdyssey-42-feature
# Switch sessions
tmux attach -t issue-42
# List sessions
tmux list-sessions
Best Practices
- One worktree per issue (don't share branches)
- Use clear naming:
<issue-number>-<description> - Keep worktrees organized in parent directory
- Use terminal multiplexer (tmux/screen) for persistent sessions
- Clean up completed worktrees (see
worktree-cleanupskill)
Limitations
- Each branch can only be checked out in ONE worktree
- Cannot be in worktree while removing it
- All worktrees share the same
.gitdirectory (some operations affect all)
References
- See
worktree-createskill for creating worktrees - See
worktree-cleanupskill for removing worktrees - worktree-strategy.md