worktrees (wt) 🌳

A friendly CLI tool for managing git worktrees with intuitive commands.

Why?

Git worktrees are powerful but the commands aren't very intuitive. This tool provides a simple, user-friendly interface for common worktree operations.

Installation

Quick install (prebuilt binary):

curl -L https://github.com/elithecho/wt/releases/download/v0.1/worktree -o worktree
chmod +x worktree
sudo mv worktree /usr/local/bin/

Or build from source:

git clone https://github.com/elithecho/wt.git
cd wt
make install

Set up shell integration (required for directory changing):

worktree install
source ~/.zshrc  # or ~/.bashrc for bash

This installs the wt shell function that enables automatic directory changing.

Add .worktrees/ to global gitignore (recommended):

git config --global core.excludesfile ~/.gitignore
echo '.worktrees/' >> ~/.gitignore

Commands

wt add <name> [branch]

Create a new worktree in the .worktrees/ directory. If no branch is specified, creates a new branch based on the name. If the requested branch already exists locally and matches the worktree name, attaches the worktree to that branch instead of trying to create it. If the branch exists but has a different name, creates a new branch named after the worktree from that branch.

wt add feature-auth                                    # Creates .worktrees/feature-auth with branch "feature-auth"
wt add hotfix main                                     # Creates branch "hotfix" from "main"
wt add file-assets-phase feature/file-assets-phase     # Attaches existing branch "feature/file-assets-phase"

wt list (aliases: ls, l)

List all worktrees with their paths, branches, and status.

wt list

wt switch <name> (aliases: s, cd, goto, go)

Navigate to a worktree by name. Automatically changes directory with shell integration.

wt switch feature-auth
wt s feature-auth        # Short alias

wt remove <name> (aliases: rm, delete, del)

Remove a worktree by name. The worktree must be clean (no uncommitted changes) unless --force is used.

wt remove feature-auth
wt rm feature-auth
wt remove --force feature-auth  # Force removal of a dirty or untracked worktree

wt original (aliases: og, main)

Navigate back to the main/original worktree.

wt og

wt clean (aliases: prune)

Clean up stale worktree references for directories that no longer exist.

wt clean

Shell Integration

After installation, run worktree install to automatically set up shell integration for your shell (bash/zsh/fish). This creates a wt function that intercepts navigation commands and handles directory changing automatically.

Usage Examples

# Create a new feature worktree (creates .worktrees/feature-login)
wt add feature-login

# List all worktrees
wt list

# Switch to the feature worktree (automatically changes directory)
wt s feature-login

# Go back to main
wt og

# Remove the feature worktree when done
wt rm feature-login

# Clean up any stale references
wt clean

Features

• 🚀 Simple commands - Intuitive interface over git worktree
• 📁 Organized storage - Worktrees stored in .worktrees/ directory
• 🔍 Smart navigation - Find worktrees by name, not full path
• 🏠 Quick return - Easy navigation back to main worktree
• 🧹 Cleanup - Automatic cleanup of stale references
• 🎨 Pretty output - Clean, readable status display

License

MIT