gwm - Git Worktree Manager

gwm is a CLI tool for efficiently managing Git worktrees using a fuzzy finder interface. It simplifies the process of creating, listing, and working with Git worktrees across multiple repositories.

Features

• 🌳 Multiple worktree creation modes - From new branches, existing branches, or remote branches
• 🔍 Interactive selection - Fuzzy finder integration for branch and worktree selection
• 🌐 Global worktree management - List and manage worktrees across all repositories
• 📊 JSON output - Programmatic interface for automation and scripts
• 🎯 Pattern matching - Find worktrees by name patterns
• ⚡ Command execution - Run commands in specific worktree directories
• 📈 Status monitoring - Monitor git status across all worktrees

Installation

Via npm (Recommended)

# Install globally
npm install -g @yukaii/gwm

# Install fzf for interactive features
# macOS
brew install fzf

# Ubuntu/Debian
sudo apt install fzf

# Arch Linux
sudo pacman -S fzf

Manual Installation

1. Clone the repository:

   git clone <repository-url>
   cd gwm

2. Make the script executable and add to PATH:

   chmod +x gwm
   sudo ln -s $(pwd)/gwm /usr/local/bin/gwm

3. Install dependencies:

   • fzf - Required for interactive features
   • git - Git worktree support (Git 2.5+)

Configuration

Configure base directory (optional):

mkdir -p ~/.config/gwm
echo 'GWM_BASE_DIR="$HOME/worktrees"' > ~/.config/gwm/config

Usage

Creating Worktrees

# Create worktree with new branch
gwm add -b feature-branch

# Create worktree from existing local branch
gwm add existing-branch

# Create worktree from remote branch
gwm add -b local-name origin/remote-branch

# Interactive branch selection
gwm add -i

Listing Worktrees

# List worktrees in current repository
gwm list

# List all worktrees globally
gwm list -g

# JSON output for scripts
gwm list --json
gwm list -g --json

Getting Worktree Paths

# Interactive selection
gwm get

# Pattern matching
gwm get feature

# Global search
gwm get -g pattern

Executing Commands

# Run command in pattern-matched worktree
gwm exec feature -- npm test

# Interactive worktree selection
gwm exec -- git status

Managing Worktrees

# Remove worktree (interactive)
gwm remove

# Remove worktree by pattern
gwm remove feature

# Remove worktree and delete branch
gwm remove -b feature

# Monitor status
gwm status
gwm status --watch

# Clean up
gwm prune

Advanced Features

Tmux Session Management

# List active tmux sessions
gwm tmux list
gwm tmux list --watch
gwm tmux list --json

# Run command in new tmux session
gwm tmux run "npm run dev"
gwm tmux run --id dev-server "npm run dev"
gwm tmux run -w feature/auth "make test"
gwm tmux run --auto-cleanup "make build"

# Attach to running session
gwm tmux attach dev-server
gwm tmux attach  # Interactive selection

# Kill sessions
gwm tmux kill dev-server
gwm tmux kill --all

Claude Code Task Management

# Add new Claude task with new branch/worktree
gwm task add claude -b feature/auth "Authentication system" -p 75

# Add task using existing worktree
gwm task add claude -w existing-feature "Continue development" -p 60

# List all tasks
gwm task list

# View task details
gwm task show task-id

# Task logs and worker management
gwm task logs
gwm task worker start --parallel 2
gwm task worker status
gwm task worker stop

Configuration

Configuration is stored in ~/.config/gwm/config:

# Base directory for storing worktrees
GWM_BASE_DIR="$HOME/worktrees"

Worktrees are organized as: $GWM_BASE_DIR/<repository-name>/<branch-name>

Examples

Development Workflow

# Start working on a new feature
gwm add -b feature/user-auth

# Switch between worktrees
cd $(gwm get feature)

# Run tests in specific worktree
gwm exec feature -- npm test

# Check status across all worktrees
gwm status -g

# Clean up when done
gwm remove -b feature/user-auth

CI/CD Integration

# Get worktree paths programmatically
gwm list --json | jq -r '.[] | select(.branch=="main") | .path'

# Automated testing across worktrees
gwm list -g --json | jq -r '.[].path' | xargs -I {} sh -c 'cd {} && npm test'

Testing

Run the test suite with:

# Install test dependencies
git submodule update --init --recursive

# Run all tests
./run_tests.sh

# Run specific test file
tests/libs/bats/bin/bats tests/add.bats

Requirements

• Bash 4.0+ - For associative arrays and modern bash features
• Git 2.5+ - For git worktree support
• fzf - For interactive selection features
• tmux - For advanced session management features
• jq - For task management JSON processing and examples

Credits

This project was inspired by gwq by d-kuro, which provides similar Git worktree management capabilities. gwm extends the concept with additional features like global worktree management, JSON output, and enhanced command-line interface.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

For bug reports and feature requests, please use the GitHub issue tracker.