A powerful CLI tool to manage Git worktrees across multiple repositories, designed for developers who work on multiple branches simultaneously using tools like Cursor.
- 🚀 Seamless Directory Switching: Automatically switches to worktree directories
- 📋 List Worktrees: View all worktrees with status and last commit info
- 🔄 Smart Branch Handling: Auto-creates tracking branches from remotes
- 🧹 Automatic Cleanup: Remove stale worktrees older than 30 days
- 💻 Cursor Integration: Open Cursor editor directly in worktree
- ⚡ Smart Completions: Zsh auto-completions that prioritize existing worktrees
- 🧭 Smart Navigation:
cd ..from worktree root takes you to ~/workspace - 🔗 Mattermost Dual-Repo: Special support for Mattermost's dual-repository workflow
# Clone the repository git clone <repo-url> cd wt # Build and install (easiest method) make install # Or manually: # Build the binary go build -o wt # Move to PATH (choose one): # Option 1: System-wide (requires sudo) sudo mv wt /usr/local/bin/ # Option 2: User-local (no sudo needed) mkdir -p ~/bin mv wt ~/bin/ export PATH="$HOME/bin:$PATH" # Add this to your .zshrc # Install shell integration wt install
The install command will:
- Add a shell function to
~/.zshrcfor seamless directory switching - Install zsh completions for commands and branch names
- Provide instructions for activation
After installation, restart your terminal or run:
source ~/.zshrc
If TAB completion doesn't appear, verify your zsh completion is initialized and the user completion directory is on $fpath:
# In your ~/.zshrc (before compinit) fpath=("$HOME/.zsh/completion" $fpath) typeset -U fpath # Initialize zsh completions autoload -Uz compinit && compinit -i
Then reload your shell:
source ~/.zshrc
If you prefer to manually add the shell function, add this to your ~/.zshrc:
# wt-shell-integration wt() { local output output=$(command wt "$@") local exit_code=$? if echo "$output" | grep -q "^__WT_CD__:"; then local new_dir=$(echo "$output" | grep "^__WT_CD__:" | cut -d':' -f2-) builtin cd "$new_dir" || return 1 # Check if there's a post-setup command to run if echo "$output" | grep -q "^__WT_CMD__:"; then local cmd=$(echo "$output" | grep "^__WT_CMD__:" | cut -d':' -f2-) echo "Running setup: $cmd" eval "$cmd" fi # Show output without markers echo "$output" | grep -v "^__WT_CD__:" | grep -v "^__WT_CMD__:" else echo "$output" fi return $exit_code } # Smart cd for worktrees - makes "cd .." from worktree root go to ~/workspace cd() { # Only intercept "cd .." from worktree root if [[ "1ドル" == ".." ]]; then local parent_dir="${PWD%/*}" # Get parent directory # Check if parent is ~/workspace/worktrees if [[ "$parent_dir" == "$HOME/workspace/worktrees" ]]; then builtin cd "$HOME/workspace" return fi fi builtin cd "$@" } # end wt-shell-integration
wt ls
Shows all worktrees for the current repository with their status and last commit date.
wt co <branch> [-b <base-branch>]
- If the worktree exists, switches to it
- If not, creates the worktree and switches to it
- If branch doesn't exist locally but exists on remote, creates a tracking branch
- If branch doesn't exist anywhere, creates a new branch from base branch (defaults to main/master)
- Automatic Mattermost Detection: When run from
~/workspace/mattermostor~/workspace/enterprise, automatically creates dual-repo worktrees
Examples:
# Standard repository wt co feature-123 # Creates worktree at ~/workspace/worktrees/my-project-feature-123/ # Mattermost repository (automatic dual-repo!) cd ~/workspace/mattermost wt co MM-123 # Creates dual worktree and switches to ~/workspace/worktrees/mattermost-MM-123/mattermost-MM-123/ # Create worktree from specific base branch wt co feature/new-ui -b develop # Create worktree from release branch wt co hotfix/urgent-fix --base release-1.0
wt clean
Removes worktrees that:
- Have no uncommitted changes (clean)
- Haven't been updated in 30+ days
Shows a confirmation prompt before removing.
wt rm <branch> [-f|--force]
- Removes the git worktree and deletes the associated directory
- Use
-fif the worktree has uncommitted changes
Example:
wt rm ai-prom-metrics wt rm MM-123 -f
wt cursor <branch> [-b <base-branch>]
Opens Cursor editor for the branch's worktree. Creates the worktree if it doesn't exist.
Examples:
# Open existing worktree wt cursor MM-123 # Create new worktree from develop and open in Cursor wt cursor feature/experiment -b develop
wt t
# or
wt toggleReturns you to the parent repository from any worktree. Intelligently detects which repository to return to based on your current location.
Examples:
# From a standard worktree cd ~/workspace/worktrees/my-project-feature/src wt t # Takes you to ~/workspace/my-project # From Mattermost dual-repo worktree cd ~/workspace/worktrees/mattermost-MM-123/mattermost-MM-123/server wt t # Takes you to ~/workspace/mattermost # From enterprise worktree cd ~/workspace/worktrees/mattermost-MM-123/enterprise-MM-123 wt t # Takes you to ~/workspace/enterprise
wt help # or just wt
Worktrees are stored in: ~/workspace/worktrees/
Format: <repo-name>-<branch-name>/
Example:
- Repository:
mattermost-plugin-ai - Branch:
MM-123 - Worktree path:
~/workspace/worktrees/mattermost-plugin-ai-MM-123/
Some repositories require additional setup after creating a worktree. The tool automatically handles this:
Mattermost Repository (mattermost/mattermost):
- Automatically detects when you're in the mattermost or enterprise repository
- Creates dual-repo worktrees with both mattermost and enterprise
- After creating a worktree, automatically runs
make setup-go-workfrom themattermost/server/directory - Configures unique ports for each worktree (starts at 8066, auto-increments)
- The command runs automatically when switching to a newly created worktree
The tool uses a shell function wrapper that:
- Captures output from the
wtbinary - Detects special
__WT_CD__:<path>marker - Executes
cd <path>in your current shell - Runs any post-setup commands if needed (via
__WT_CMD__marker) - Shows remaining output
This provides seamless directory switching without subshell limitations, and automatically handles repository-specific setup commands.
The installation includes a smart cd wrapper that makes navigation more intuitive:
When you're at the root of a worktree (e.g., ~/workspace/worktrees/mattermost-MM-123/):
cd ..→ Takes you to~/workspace(your main workspace)- This treats worktrees as siblings to your main repositories
When you're in a subdirectory (e.g., ~/workspace/worktrees/mattermost-MM-123/server/):
cd ..→ Works normally, goes to parent directory
All other cd commands work exactly as expected.
This makes worktrees feel naturally integrated into your workspace hierarchy without needing to navigate through the worktrees/ directory.
The zsh completions intelligently prioritize what you're most likely to want:
When you press TAB after wt co or wt cursor:
- Existing worktrees are shown first with "(existing worktree)" label
- Local branches come next with "(local branch)" label
- Remote branches appear last with "(remote branch)" label
Example:
wt co agents-<TAB> # Shows: # agents-prom-grafana -- existing worktree # agents-dev -- local branch # agents-staging -- remote branch wt cursor ai-<TAB> # Completes to existing worktree: wt cursor ai-prom-metrics
This makes it fast to switch between your active worktrees without typing full branch names.
For developers working on Mattermost, wt automatically detects when you're in the mattermost repository and creates dual-repo worktrees using the standard commands - no special commands needed!
Ensure you have both repositories cloned:
~/workspace/mattermost/ # mattermost/mattermost monorepo ~/workspace/enterprise/ # mattermost/enterprise
Just use the regular wt co command from the mattermost or enterprise repository:
# From mattermost repo - automatically creates dual worktree cd ~/workspace/mattermost wt co MM-12345 # Automatically drops you into: ~/workspace/worktrees/mattermost-MM-12345/mattermost-MM-12345/ # From enterprise repo - same dual worktree, different landing directory cd ~/workspace/enterprise wt co MM-12345 # Automatically drops you into: ~/workspace/worktrees/mattermost-MM-12345/enterprise-MM-12345/ # Create from a specific base branch wt co MM-12345 -b master
This creates a unified worktree structure:
~/workspace/worktrees/mattermost-MM-12345/
├── [base config files] # CLAUDE.md, mise.toml, etc.
├── mattermost-MM-12345/ # Worktree from mattermost repo
│ ├── server/
│ ├── webapp/
│ └── ...
├── enterprise-MM-12345/ # Worktree from enterprise repo
│ └── ...
├── mattermost -> mattermost-MM-12345/ # Symlink for make scripts
└── enterprise -> enterprise-MM-12345/ # Symlink for make scripts
Note:
- The subdirectories include the branch name (e.g.,
mattermost-MM-12345) so that each Cursor window has a unique title, making it easy to distinguish between multiple worktrees. - Symlinks (
mattermostandenterprise) are created for compatibility with Mattermost's build scripts that reference../../enterprise.
What it automatically does:
- Detects you're in the mattermost or enterprise repository
- Creates worktrees for both
mattermostandenterpriserepositories - Copies base configuration files from your main mattermost repo
- Copies
go.work*files and other development configurations - Updates
config.jsonwith unique ports (starts at 8066, auto-increments) - Automatically runs
make setup-go-workin the server directory - Switches to the appropriate subdirectory based on which repo you started from
Again, just use the standard command:
# Standard removal - automatically detects and removes from both repos wt rm MM-12345 # Force removal (for dirty worktrees) wt rm MM-12345 -f
# Open existing or create new Mattermost worktree in Cursor
wt cursor MM-12345# Return to parent repository from anywhere in a worktree wt t # Example: cd ~/workspace/worktrees/mattermost-MM-12345/mattermost-MM-12345/server wt t # Takes you back to ~/workspace/mattermost
# Start in your main repository cd ~/workspace/my-project # Create worktree for ticket wt co feature-123 # Now in ~/workspace/worktrees/my-project-feature-123/ # Open another Cursor window for a different branch wt cursor feature-456 # List all worktrees wt ls # Clean up old worktrees wt clean
# Start in mattermost repo cd ~/workspace/mattermost # Create dual-repo worktree for ticket MM-12345 (uses standard command!) wt co MM-12345 # Now in ~/workspace/worktrees/mattermost-MM-12345/mattermost-MM-12345/ # Automatically created worktrees in both mattermost and enterprise repos # The server runs on auto-assigned port (e.g., 8066) # Access at http://localhost:8066 # Work on another ticket in parallel wt cursor MM-12346 # Server runs on different port (e.g., 8069) # Toggle back to main repo wt t # Back in ~/workspace/mattermost # Remove when done (standard command automatically removes both worktrees) wt rm MM-12345
- Go 1.16+ (for building)
- Git 2.5+ (for worktree support)
- Zsh (for shell integration)
- Cursor CLI (optional, for
wt cursorcommand)
Feel free to submit issues and pull requests!
MIT