DEV Community

Cover image for wtp: A Better Git Worktree CLI Tool
Satoshi Ebisawa
Satoshi Ebisawa

Posted on

wtp: A Better Git Worktree CLI Tool

#git #go #productivity

Working with multiple tasks in parallel using Claude Code has become my daily routine, making git worktree essential for my workflow.

While git worktree is convenient, after creating and deleting worktrees multiple times daily, I started noticing some pain points:

  • The worktree add command is somewhat verbose and tedious
    • When creating worktrees based on branch names, you end up typing the branch name twice
    • For existing branches: git worktree add .worktrees/hoge hoge
    • For new branches: git worktree add -b hoge .worktrees/hoge
  • I almost always need to manually copy .env files and run npm install after creation
    • While Claude Code helps with this when needed, it's more efficient to automate these repetitive tasks
  • Cleaning up both worktree and branch separately after completing work is tedious

While a simple shell script could solve these requirements, I decided to build a proper CLI tool with Claude Code.

https://github.com/satococoa/wtp

Main Features

wtp add

While git worktree requires specifying both path and branch name, wtp only needs the branch name.

# Create new branch with worktree
wtp add -b feature/new-auth

# Review PR (existing remote branch)
wtp add fix/hogefuga
Enter fullscreen mode Exit fullscreen mode

The worktree path is automatically generated according to .wtp.yml configuration (defaults to ../worktrees). Remote branch tracking is also automatic.

post create hook

Define post_create in .wtp.yml to automatically execute commands after worktree creation.

hooks:
  post_create:
    - type: copy
      from: .env.example
      to: .env
    - type: command
      command: "npm install"
Enter fullscreen mode Exit fullscreen mode

Automate common tasks like copying .env files and installing dependencies.

remove --with-branch

Since deleting worktree and branch separately is tedious, I made it possible to delete both together.

# With regular git worktree
git worktree remove feature/done
git branch -d feature/done
Enter fullscreen mode Exit fullscreen mode

With wtp, you can delete both in one command.

wtp remove feature/done --with-branch
Enter fullscreen mode Exit fullscreen mode

Warnings are shown for unmerged branches.

Usage Examples

When urgent fixes come in during development 

# Create new worktree while keeping current feature work
wtp add -b hotfix/urgent-bug

# Fix bug and create PR
# ...

# Delete both worktree and branch after completion
wtp remove hotfix/urgent-bug --with-branch

# Return to original work
wtp cd feature/new-auth
Enter fullscreen mode Exit fullscreen mode

PR Review 

# When review request comes in (for existing remote branch)
wtp add feature/pr-123

# Actually run the application for review
# ...

# Delete worktree after review (remote branch remains)
wtp remove feature/pr-123
Enter fullscreen mode Exit fullscreen mode

Other Features

wtp list

Display worktree list in a clean format.

% wtp list
PATH                           BRANCH           STATUS  HEAD
----                           ------           ------  ----
@                              main             managed 99c30171
feature/add-auth               feature/add-auth managed 99c30171
fix/123/hogefuga*              fix/123/hogefuga managed 99c30171
Enter fullscreen mode Exit fullscreen mode

wtp cd

Navigate between worktrees with shell integration and tab completion.

# Move to worktree
wtp cd feature/auth

# Return to main worktree
wtp cd @

# Tab completion is available
wtp cd <TAB>
Enter fullscreen mode Exit fullscreen mode

Configuration File (.wtp.yml)

Define project-specific settings. Generate initial config with wtp init:

wtp init
Enter fullscreen mode Exit fullscreen mode

Complete configuration file structure:

version: "1.0"
defaults:
  base_dir: "../worktrees"  # worktree creation location

hooks:
  post_create:
    # File copying
    - type: copy
      from: ".env.example"
      to: ".env"

    # Command execution (environment variables can be set)
    - type: command
      command: "bundle install"
      env:
        RAILS_ENV: "development"
Enter fullscreen mode Exit fullscreen mode

Installation

Homebrew 

brew install satococoa/tap/wtp
Enter fullscreen mode Exit fullscreen mode

Go install 

go install github.com/satococoa/wtp/cmd/wtp@latest
Enter fullscreen mode Exit fullscreen mode

Shell Integration

When installed via Homebrew:

  • zsh: Completion files are automatically placed. No additional setup needed if FPATH is correctly configured
  • bash/fish: Completion files are placed, but refer to each shell's documentation for detailed setup

Manual shell integration setup (when installed via go install, etc.):

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

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

# Fish: Add to ~/.config/fish/config.fish
wtp completion fish | source
Enter fullscreen mode Exit fullscreen mode

📝 I primarily use zsh, so bash/fish functionality is untested

Why Go?

I consulted with Claude Code on language choice. Reasons for choosing Go:

  • Single binary distribution (easy installation via brew or go install)
  • Easy cross-platform support
  • Static typing helps AI write more stable code

After actually developing with it, I found Go well-suited for Agentic Coding. With static typing and built-in fmt and linting, minimal configuration is needed. Adding golangci-lint and GoReleaser makes CI/CD work seamlessly.

Summary

I created a tool to solve the tedious aspects of git worktree. If you have similar frustrations, please give it a try.

GitHub: https://github.com/satococoa/wtp

Top comments (0)