git-worktree
Manage git worktrees for parallel development. Use when the user wants to work on multiple branches simultaneously, create isolated environments for features/fixes, or clean up completed worktrees.
When & Why to Use This Skill
The Git Worktree Manager skill optimizes parallel development workflows by providing a unified interface for managing multiple Git branches in isolated directories. It automates environment configuration, simplifies context switching without the need for stashing, and ensures a clean repository through automated cleanup of stale worktrees, significantly boosting developer productivity and workspace organization.
Use Cases
- Parallel Feature Development: Create dedicated, isolated environments for different features or bug fixes, allowing you to work on multiple branches simultaneously without cross-contamination.
- Seamless PR Reviews: Review and test multiple pull requests in separate directories concurrently without interrupting your current coding session or losing uncommitted changes.
- Automated Environment Management: Automatically synchronize .env configuration files from the main repository to new worktrees, ensuring consistent local development setups across all branches.
- Repository Maintenance: Efficiently identify and remove merged, stale, or missing worktree directories to keep your local development environment organized and free of clutter.
| name | git-worktree |
|---|---|
| description | Manage git worktrees for parallel development. Use when the user wants to work on multiple branches simultaneously, create isolated environments for features/fixes, or clean up completed worktrees. |
Git Worktree Manager
Overview
This skill provides a unified interface for managing git worktrees, enabling isolated parallel development. Worktrees allow you to have multiple branches checked out simultaneously in separate directories.
Key features:
- Automatic
.envfile copying from main repo to new worktrees - Unified storage in
.worktrees/directory - Cleanup of merged and stale worktrees
When to Use This Skill
- Creating isolated environments for feature development
- Working on multiple branches simultaneously
- Reviewing PRs without stashing current work
- Cleaning up completed feature branches
Critical: Always Use the Manager Script
Always use the worktree-manager.sh script rather than raw git worktree commands. The script handles:
- Automatic
.envfile copying to new worktrees - Consistent storage in
.worktrees/directory - Proper
.gitignoremanagement
Core Commands
All operations use the unified worktree-manager.sh script:
bash scripts/worktree-manager.sh <command> [options]
Create Worktree
worktree-manager.sh create <branch-name> [source-branch]
Creates a new worktree in .worktrees/<branch-name>. If the branch exists, it checks it out. If not, creates a new branch from the source (defaults to main/master).
List Worktrees
worktree-manager.sh list
Shows all worktrees with their branch, commit, and status (clean/dirty/missing).
Switch Worktree
worktree-manager.sh switch <branch-name|path>
Provides information for switching to a worktree by branch name or path.
Cleanup Worktrees
worktree-manager.sh cleanup [--force]
Identifies and removes:
- Worktrees with merged branches
- Worktrees with deleted remote branches
- Missing worktree directories
Use --force to skip confirmation prompt.
Copy Environment Files
worktree-manager.sh copy-env [worktree-path|branch-name]
Copies .env* files (excluding .env.example) from the main repo to a worktree. Useful for:
- Adding env files to existing worktrees created before this feature
- Refreshing env files after main repo changes
If run inside a worktree without arguments, copies to current location.
Storage
Worktrees are stored in .worktrees/ within the repository root. This directory is automatically added to .gitignore.
Example Workflow
# Start new feature
worktree-manager.sh create feature-auth
# Work in the new worktree
cd .worktrees/feature-auth
# List all worktrees
worktree-manager.sh list
# When done, clean up
worktree-manager.sh cleanup
Troubleshooting
Missing .env files in existing worktrees
If you have existing worktrees created before the automatic env copying feature:
bash scripts/worktree-manager.sh copy-env feature-branch
Or from within the worktree directory:
bash scripts/worktree-manager.sh copy-env