A powerful Git worktree management tool that extends git's worktree functionality with automated setup, branch tracking, and project-specific hooks.
git-worktree pain:
git worktree add ../project-worktrees/feature/auth feature/auth wtp
solution: wtp add feature/auth
wtp automatically generates sensible paths based on branch names. Your
feature/auth branch goes to ../worktrees/feature/auth - no redundant typing,
no path errors.
git-worktree pain: Remove worktree, then manually delete the branch. Forget
the second step? Orphaned branches accumulate. wtp solution:
wtp remove --with-branch feature/done - One command removes both
Keep your repository clean. When a feature is truly done, remove both the worktree and its branch in one atomic operation. No more forgotten branches cluttering your repo.
git-worktree pain: Create worktree → Copy .env → Install deps → Run
migrations → Finally start coding wtp solution: Configure once in
.wtp.yml, then every wtp add runs your setup automatically
hooks:
post_create:
- type: copy
from: ".env.example"
to: ".env"
- type: command
command: "npm install && npm run db:setup"Perfect for microservices, monorepos, or any project with complex setup requirements.
git-worktree pain: cd ../../../worktrees/feature/auth (if you remember the
path) wtp solution: wtp cd feature/auth with tab completion
Jump between worktrees instantly. Use wtp cd @ to return to your main
worktree. No more terminal tab confusion.
- 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
View all releases and changelogs: GitHub Releases
Latest stable version: See releases
brew install satococoa/tap/wtpgo install github.com/satococoa/wtp/cmd/wtp@latestDownload 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/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# 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
# Create new branch tracking a different remote branch
# → Creates worktree at ../worktrees/feature/test with branch tracking origin/main
wtp add -b feature/test 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 -b feature/shared upstream/feature/shared# List all worktrees
wtp list
# Example output:
# PATH BRANCH HEAD
# ---- ------ ----
# @ (main worktree)* main c72c7800
# feature/auth feature/auth def45678
# ../project-hotfix hotfix/urgent abc12345
# Remove worktree only (by worktree name)
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 deletionwtp uses .wtp.yml for project-specific configuration:
version: "1.0"
defaults:
# Base directory for worktrees (relative to project root)
base_dir: "../worktrees"
hooks:
post_create:
# Copy gitignored files from main worktree to new worktree
# Note: 'from' is relative to main worktree, 'to' is relative to new worktree
- type: copy
from: ".env" # Copy actual .env file (gitignored)
to: ".env"
- type: copy
from: ".claude" # Copy AI context file (gitignored)
to: ".claude"
# Execute commands in the new worktree
- type: command
command: "npm install"
env:
NODE_ENV: "development"
- type: command
command: "make db:setup"
work_dir: "."Copy hooks are designed to help you bootstrap new worktrees using files from your main worktree (even if they are gitignored):
from: path is always resolved relative to the main worktree.to: path is resolved relative to the newly created worktree.- Supports files and directories, including entries ignored by Git (e.g.,
.env,.claude,.cursor/).
Examples:
hooks:
post_create:
# Copy local env and AI context from MAIN worktree into the new worktree
- type: copy
from: ".env"
to: ".env"
- type: copy
from: ".claude"
to: ".claude"
# Directory copy also works
- type: copy
from: ".cursor/"
to: ".cursor/"This behavior applies regardless of where you run wtp add from (main worktree or any other worktree).
Shell completions are automatically installed and should work immediately! No manual setup required.
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 | sourceThis enables:
- Tab completion for all wtp commands, flags, and options
- Branch name completion for
wtp add - Worktree name completion for
wtp removeandwtp cd - The
wtp cdcommand for quick navigation to worktrees
Once shell integration is enabled, you can quickly change to any worktree:
# Change to a worktree by its name
wtp cd feature/auth
# Change to the root worktree using the '@' shorthand
wtp cd @
# Tab completion works!
wtp cd <TAB>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.
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 overrideWe welcome contributions! Please see our Contributing Guide for details.
# Clone repository
git clone https://github.com/satococoa/wtp.git
cd wtp
# Install dependencies
go mod download
# Run tests
go tool task test
# Build
go tool task build
# Run locally
./wtp --helpMIT License - see LICENSE file for details.
Inspired by git-worktree and the need for better multi-branch development workflows.