wtp

wtp (Worktree Plus)

A powerful Git worktree management tool that extends git's worktree functionality with automated setup, branch tracking, and project-specific hooks.

Features

Core Commands

• wtp init - Initialize configuration file
• wtp add - Clean and unambiguous worktree creation
  • Automatic path generation: wtp add feature/auth (no redundant typing)
  • Explicit path support: wtp add --path /custom/path feature/auth (no ambiguity)
  • Transparent wrapper: All git worktree options supported
  • Automatic remote tracking: Tracks remote branches when local branch doesn't exist
  • Multiple remote handling: Detects and reports when branch exists in multiple remotes
  • Post-create hooks execution
• wtp remove - Remove worktree
  • Remove worktree only (git worktree compatible)
  • Remove with branch (--with-branch option for convenience)
  • Force removal (--force option)
• wtp list - List all worktrees with status
• wtp cd - Change directory to worktree (requires shell integration)

Advanced Features

• Post-create hooks
  • Copy files from main worktree
  • Execute commands
• Shell completion (with custom completion for branches and worktrees)
  • Bash completion with branch/worktree name completion
  • Zsh completion with branch/worktree name completion
  • Fish completion with branch/worktree name completion
• Cross-platform support
  • Linux (x86_64, ARM64)
  • macOS (Apple Silicon only)
• Better error messages
  • Contextual error descriptions with clear causes
  • Actionable suggestions for resolution
  • Examples and helpful tips

Requirements

• Git 2.17 or later (for worktree support)
• One of the following operating systems:
  • Linux (x86_64 or ARM64)
  • macOS (Apple Silicon M1/M2/M3)
• One of the following shells (for completion support):
  • Bash
  • Zsh
  • Fish

Installation

Using Homebrew (macOS/Linux)

brew install satococoa/tap/wtp

Using Go

go install github.com/satococoa/wtp/cmd/wtp@latest

Download Binary

Download the latest binary from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Darwin_arm64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Linux_x86_64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Linux_arm64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

From Source

git clone https://github.com/satococoa/wtp.git
cd wtp
go build -o wtp ./cmd/wtp
sudo mv wtp /usr/local/bin/  # or add to PATH

Quick Start

Automatic Path Generation (Recommended)

# Create worktree from existing branch (local or remote)
# → Creates worktree at ../worktrees/feature/auth
# Automatically tracks remote branch if not found locally
wtp add feature/auth

# Create worktree with new branch
# → Creates worktree at ../worktrees/feature/new-feature
wtp add -b feature/new-feature

# Create new branch from specific commit
# → Creates worktree at ../worktrees/hotfix/urgent
wtp add -b hotfix/urgent abc1234

# Use all git worktree options
# → Creates worktree at ../worktrees/feature/test
wtp add -b feature/test --track origin/main

# Remote branch handling examples:

# Automatically tracks remote branch if not found locally
# → Creates worktree tracking origin/feature/remote-only
wtp add feature/remote-only

# If branch exists in multiple remotes, shows helpful error:
# Error: branch 'feature/shared' exists in multiple remotes: origin, upstream
# Please specify the remote explicitly (e.g., --track origin/feature/shared)
wtp add feature/shared

# Explicitly specify which remote to track
wtp add --track upstream/feature/shared feature/shared

# Control directory change behavior
wtp add --cd feature/auth        # Always change to new worktree
wtp add --no-cd feature/auth      # Never change directory
# Without flags, uses cd_after_create setting from .wtp.yml

Explicit Path Specification (Full Flexibility)

# Create worktree at custom absolute path
wtp add --path /tmp/experiment feature/auth

# Create worktree at custom relative path
wtp add --path ./custom-location feature/auth

# Create detached HEAD worktree from commit
wtp add --path /tmp/debug --detach abc1234

# All git worktree options work with explicit paths
wtp add --path /tmp/test --force feature/auth

# No ambiguity: foobar/foo is always treated as branch name
wtp add --path /custom/location foobar/foo

Management Commands

# List all worktrees
wtp list

# Remove worktree only
wtp remove feature/auth
wtp remove --force feature/auth  # Force removal even if dirty

# Remove worktree and its branch
wtp remove --with-branch feature/auth              # Only if branch is merged
wtp remove --with-branch --force-branch feature/auth  # Force branch deletion

Configuration

wtp uses .wtp.yml for project-specific configuration:

version: "1.0"
defaults:
  # Base directory for worktrees (relative to project root)
  base_dir: "../worktrees"
  
  # Automatically change to the new worktree directory after creation
  cd_after_create: true

hooks:
  post_create:
    # Copy files from repository root to new worktree
    - type: copy
      from: ".env.example"
      to: ".env"

    - type: copy
      from: "config/database.yml.example"
      to: "config/database.yml"

    # Execute commands in the new worktree
    - type: command
      command: "npm"
      args: ["install"]
      env:
        NODE_ENV: "development"

    - type: command
      command: "make"
      args: ["db:setup"]
      work_dir: "."

Shell Integration

Quick Setup (Recommended)

If installed via Homebrew or Package Manager

Shell completions are automatically installed and should work immediately! No manual setup required.

Manual Setup

If you installed wtp manually, add the following to your shell configuration file:

# Bash: Add to ~/.bashrc
eval "$(wtp completion bash)"

# Zsh: Add to ~/.zshrc
eval "$(wtp completion zsh)"

# Fish: Add to ~/.config/fish/config.fish
wtp completion fish | source

This enables:

• Tab completion for all wtp commands, flags, and options
• Branch name completion for wtp add and wtp remove
• Worktree name completion for wtp cd
• The wtp cd command for quick navigation to worktrees

Using the cd Command

Once shell integration is enabled, you can quickly change to any worktree:

# Change to a worktree by branch name
wtp cd feature/auth

# Tab completion works!
wtp cd <TAB>

Worktree Structure

With the default configuration (base_dir: "../worktrees"):

<project-root>/
├── .git/
├── .wtp.yml
└── src/

../worktrees/
├── main/
├── feature/
│   ├── auth/          # wtp add feature/auth
│   └── payment/       # wtp add feature/payment
└── hotfix/
    └── bug-123/       # wtp add hotfix/bug-123

Branch names with slashes are preserved as directory structure, automatically organizing worktrees by type/category.

Error Handling

wtp provides clear error messages:

# Branch not found
Error: branch 'nonexistent' not found in local or remote branches

# Multiple remotes have same branch
Error: branch 'feature' exists in multiple remotes: origin, upstream. Please specify remote explicitly

# Worktree already exists
Error: failed to create worktree: exit status 128

# Uncommitted changes
Error: Cannot remove worktree with uncommitted changes. Use --force to override

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/satococoa/wtp.git
cd wtp

# Install dependencies
go mod download

# Run tests
make test

# Build
make build

# Run locally
./wtp --help

Roadmap

v0.1.0 (MVP) ✅ COMPLETED

• Basic commands (add, remove, list)
• Local branch support
• Remote branch tracking
• Configuration file support
• Post-create hooks

v0.2.0

• Shell completion (with custom branch/worktree completion)
• Init command for configuration
• Branch creation (-b flag)
• Hybrid approach (automatic + explicit path support)

v0.3.0

• Remove with branch (--with-branch option)
• Shell integration (cd command)
• Multiple remote handling
• Better error messages

v1.0.0

• Stable release
• Full test coverage
• Package manager support

Future Ideas

• git wtp status - Show status of all worktrees
• git wtp foreach - Run command in all worktrees
• git wtp clean - Remove merged worktrees
• VSCode extension
• GitHub Actions integration

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by git-worktree and the need for better multi-branch development workflows.