Git Worktree Helper (git-wt)

A comprehensive CLI tool for managing git worktrees with advanced features including checkpointing, pull request integration, interactive mode, and tree visualization.

🚀 Features

Core Worktree Management

• ✅ Create worktrees for existing or new branches
• ✅ List worktrees with detailed status information
• ✅ Switch between worktrees
• ✅ Delete worktrees with safety checks
• ✅ Batch operations (create/delete multiple worktrees)
• ✅ Prune stale worktrees

Advanced Status & Health

• ✅ Real-time git status for each worktree
• ✅ Health checks (accessibility, git validity)
• ✅ Remote tracking status (ahead/behind counts)
• ✅ Last activity timestamps
• ✅ Conflict detection

Checkpoint System (Stash-based)

• ✅ Create checkpoints before dangerous operations
• ✅ Restore from any checkpoint
• ✅ List and manage checkpoints
• ✅ Reset worktree to specific checkpoint

Pull Request Integration

• ✅ Create PRs directly from worktrees (requires GitHub CLI)
• ✅ List pull requests by state
• ✅ Merge PRs with different strategies (merge/squash/rebase)
• ✅ Automatic worktree cleanup after merge

Interactive Mode

• ✅ Full interactive CLI with fuzzy search
• ✅ Menu-driven operations
• ✅ Visual dashboard with statistics
• ✅ Guided workflows

Visualization

• ✅ Tree view of worktree structure
• ✅ Project directory tree
• ✅ Colored output with status indicators
• ✅ Dashboard with worktree statistics

Configuration & Customization

• ✅ YAML-based configuration
• ✅ Custom aliases
• ✅ Templates and presets
• ✅ User preferences

Shell Integration

• ✅ Bash and Zsh completions
• ✅ Cross-worktree operations
• ✅ Sync all worktrees with remotes

📦 Installation

# Clone and install
git clone <this-repo>
cd git-worktree-helper
npm install
npm run build

# Install globally
npm run install-global

# Or install manually
npm install -g .

🎯 Quick Start

# Interactive mode (recommended for beginners)
git-wt interactive

# List worktrees with detailed status
git-wt status

# Create a new worktree
git-wt create feature-auth

# Create with new branch
git-wt create -b feature-payments

# Show dashboard
git-wt dashboard

📋 Command Reference

Basic Commands

# List worktrees
git-wt list                    # Basic list
git-wt list --detailed         # With status info
git-wt list --tree            # Tree visualization

# Create worktree
git-wt create <branch> [path]  # From existing branch
git-wt create -b <branch>      # Create new branch

# Switch worktree
git-wt switch <branch-or-path>

# Delete worktree
git-wt delete <branch-or-path>
git-wt delete -f <path>        # Force delete

Advanced Features

# Interactive mode
git-wt interactive             # Full interactive CLI

# Status and dashboard
git-wt status                  # Detailed status all
git-wt status <worktree>       # Status for specific worktree
git-wt dashboard               # Visual dashboard

# Checkpoints (stash-based)
git-wt checkpoint --create <path> "message"    # Create checkpoint
git-wt checkpoint --list <path>                # List checkpoints
git-wt checkpoint --restore <path> [ref]       # Restore checkpoint
git-wt checkpoint --delete <path> <ref>        # Delete checkpoint

# Pull requests (requires GitHub CLI)
git-wt pr --create <path> --title "Fix bug"    # Create PR
git-wt pr --list open                          # List open PRs
git-wt pr --merge 123 --squash                 # Merge with squash

# Batch operations
git-wt batch --create "feat1,feat2,feat3"      # Create multiple
git-wt batch --delete "path1,path2" --force    # Delete multiple
git-wt batch --prune                           # Prune stale worktrees

# Sync operations
git-wt sync                    # Sync all worktrees with remotes

# Configuration
git-wt config --view           # View current config
git-wt config --path           # Show config file path
git-wt config --reset          # Reset to defaults

Tree Visualization

git-wt tree                    # Project structure (depth: 3)
git-wt tree --depth 5          # Custom depth
git-wt list --tree             # Worktree tree view

⚙️ Configuration

The tool creates a configuration file at ~/.git-worktree-helper/config.yml:

paths:
  defaultWorkspaceRoot: /path/to/workspace
  templatesDir: ~/.git-worktree-helper/templates

display:
  showCommitHash: true
  showLastActivity: true
  compactMode: false
  maxTreeDepth: 3

behavior:
  autoFetch: false
  autoTrackRemote: true
  confirmDangerous: true
  cleanupOnDelete: true

templates:
  feature:
    name: feature
    description: Feature branch template
    pathPattern: '{repo}-{branch}'
    branches: [main, develop]
    setupScript: npm install

aliases:
  ls: list
  sw: switch
  rm: delete
  st: status
  dash: dashboard

🔧 Shell Completions

# Bash completion
source completions/git-wt.bash

# Zsh completion  
source completions/git-wt.zsh

# Add to your shell's rc file for permanent installation

💡 Usage Examples

Checkpoint Workflow

# Create checkpoint before risky changes
git-wt checkpoint --create . "Before refactoring"

# Make dangerous changes...
# Something went wrong!

# Restore from checkpoint
git-wt checkpoint --restore .

PR Workflow

# Create feature worktree
git-wt create -b feature-login

# Work on feature...
# Push changes

# Create PR
git-wt pr --create . --title "Add login feature" --base main

# After review, merge PR
git-wt pr --merge 123 --squash --delete-worktree

Batch Workflow

# Create multiple worktrees for parallel development
git-wt batch --create "feature-a,feature-b,hotfix-c"

# Work on features...

# Clean up completed features
git-wt batch --delete "feature-a,feature-b" --force

Interactive Workflow

# Start interactive mode
git-wt interactive

# Navigate through menus:
# - View dashboard
# - Create/switch/delete worktrees
# - Manage checkpoints
# - Handle PRs
# - Batch operations

🛠️ Requirements

• Node.js 16+
• Git repository
• GitHub CLI (gh) for PR operations (optional)
• TypeScript (for development)

🚧 Development

npm run dev         # Watch mode compilation
npm run build       # Build for production
npm start           # Run built version

📄 License

MIT

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🔍 Troubleshooting

Common Issues

1. Command not found: Make sure the tool is installed globally (npm install -g .)
2. Permission errors: Check file permissions and git repository access
3. GitHub CLI errors: Install and authenticate GitHub CLI for PR operations
4. Interactive mode issues: Ensure terminal supports ANSI colors and UTF-8

Debug Mode

Set DEBUG=git-wt:* environment variable for verbose logging.

Happy worktree management! 🌳