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.

⭐13stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

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.
namegit-worktree
descriptionManage 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 .env file 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 .env file copying to new worktrees
  • Consistent storage in .worktrees/ directory
  • Proper .gitignore management

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