@t.goto/git-worktree-manager v1.0.0

Git Worktree Manager (GWM)

🌿 Universal Git worktree management tool with project-specific install commands

Overview

GWM automates the creation and management of Git worktrees with intelligent project detection and customizable install commands. It supports multiple project types and provides a consistent workflow across different development environments.

Features

• 🔍 Auto-detection: Automatically detects project type (Laravel, React, Django, etc.)
• 📦 Custom Install Commands: Configurable dependency installation per project
• 🐳 Docker Integration: Built-in Docker Compose support
• 🪝 Custom Hooks: Pre/post install hooks for project-specific setup
• ⚙️ Environment-aware: Different commands for local, docker, production environments
• 📋 Template System: Pre-configured templates for common project types

Installation

NPM (Recommended)

# グローバルインストール
npm install -g gwm-worktree-manager

# インストール確認
gwm --version

Yarn

# グローバルインストール
yarn global add gwm-worktree-manager

# インストール確認
gwm --version

Local Development

git clone <repository>
cd gwm
npm install
npm link

# または
npm install -g .

Requirements

• Node.js >= 14.0.0
• Git >= 2.5.0
• npm or yarn

Quick Start

1. Initialize in your project

cd your-project
gwm init

This creates a .worktree.yml configuration file with auto-detected settings.

2. Create a worktree

gwm create feature-branch

3. List worktrees

gwm list

4. Remove a worktree

gwm remove feature-branch

Configuration

The .worktree.yml file controls how GWM manages your worktrees:

project:
  name: "my-project"
  type: "php-laravel"

install:
  dependencies: "composer install --no-interaction"
  
environments:
  docker:
    install: "docker compose exec php composer install"
    
scripts:
  test: "php artisan test"
  build: "npm run build"
  quality: "vendor/bin/phpcs && vendor/bin/phpstan"

docker:
  enabled: true
  service: "php"

worktree:
  directory: "../worktrees"
  auto_install: true
  auto_setup: true

Supported Project Types

PHP Laravel

• Detection: composer.json + artisan + Laravel framework
• Install: composer install --no-interaction --optimize-autoloader
• Features: Auto .env creation, Laravel-specific Makefile

Node.js React

• Detection: package.json + React dependencies
• Install: npm ci
• Features: Package.json scripts integration

Python Django

• Detection: manage.py or requirements.txt with Django
• Install: pip install -r requirements.txt
• Features: Virtual environment support

Generic

• Fallback: For any project type not specifically supported
• Customizable: Fully configurable via .worktree.yml

Custom Hooks

Create custom setup logic in .worktree/hooks/install.sh:

#!/bin/bash
WORKTREE_PATH="$1"
PROJECT_TYPE="$2"
BRANCH_NAME="$3"

echo "Setting up $BRANCH_NAME..."

# Custom setup logic here
case "$PROJECT_TYPE" in
    "php-laravel")
        cd "$WORKTREE_PATH"
        php artisan key:generate
        php artisan storage:link
        ;;
esac

Commands

gwm init

Initialize worktree configuration for current project

• Auto-detects project type
• Generates .worktree.yml configuration
• Creates hooks directory with samples

gwm create <branch-name>

Create a new worktree for the specified branch

• Creates Git worktree
• Runs install commands
• Sets up project-specific files
• Creates worktree-specific Makefile (if applicable)

Options:

• --force: Force creation even if branch exists
• --no-install: Skip dependency installation

gwm remove <branch-name>

Remove an existing worktree

• Removes Git worktree
• Cleans up all worktree-specific files

Options:

• --force: Skip confirmation prompt

gwm list

List all existing worktrees

• Shows worktree paths and branch names
• Indicates main worktree

gwm status

Show worktree manager status and configuration

• Project information
• Configuration summary
• Worktree count

Docker Integration

For Docker-based projects, GWM automatically detects and configures Docker commands:

docker:
  enabled: true
  service: "php"
  compose_file: "docker-compose.yml"

environments:
  docker:
    install: "docker compose exec php composer install"

Commands will automatically use Docker when configured.

Advanced Usage

Environment-specific Commands

environments:
  local:
    install: "composer install"
  docker:
    install: "docker compose exec php composer install"
  production:
    install: "composer install --no-dev --optimize-autoloader"

Set environment: NODE_ENV=docker gwm create feature-branch

Custom Scripts

scripts:
  test: "php artisan test"
  quality: "vendor/bin/phpcs && vendor/bin/phpstan"
  deploy: "rsync -av . production:/"

These are included in generated Makefiles and documentation.

Worktree Directory Customization

worktree:
  directory: "../my-worktrees"  # Custom directory
  auto_install: false           # Manual install
  auto_setup: false            # Manual setup

Examples

Laravel Project

# Initialize
gwm init  # Detects: php-laravel

# Create feature worktree
gwm create feature-payment
# → Creates worktree with:
#   - composer install
#   - .env file from .env.example
#   - Laravel-specific Makefile
#   - Docker integration

# Work in worktree
cd ../worktrees/feature-payment
make test
make migrate

React Project

# Initialize
gwm init  # Detects: node-react

# Create worktree
gwm create feature-ui
# → Creates worktree with:
#   - npm ci
#   - Basic Makefile with npm scripts

# Development
cd ../worktrees/feature-ui
npm start

Troubleshooting

Permission Issues

chmod +x .worktree/hooks/install.sh

Docker Not Found

Ensure Docker is running and docker compose is available.

Custom Project Type

For unsupported project types, use generic and customize .worktree.yml:

project:
  type: "generic"
  
install:
  dependencies: "your-custom-install-command"

Contributing

1. Fork the repository
2. Create a feature branch: gwm create feature-new-adapter
3. Add your adapter in lib/adapters/
4. Add tests
5. Submit a pull request

Creating Custom Adapters

// lib/adapters/your-framework.js
module.exports = {
  name: 'your-framework',
  
  async detect(projectRoot) {
    // Detection logic
    return true/false;
  },
  
  install: {
    dependencies: 'your-install-command'
  },
  
  scripts: {
    test: 'your-test-command',
    build: 'your-build-command'
  }
};

License

MIT License - see LICENSE file for details.

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📚 Documentation: Wiki