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

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

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

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

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

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

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

Create a new worktree in the .worktrees/ directory. The second argument is resolved in this order:

1. An existing local branch whose leaf name matches <name> — the worktree is attached to it.
2. Anything git can resolve to a commit — a local branch, a remote-tracking ref such as origin/main, a tag, or a SHA — is used as the start point, and the new branch is named after the worktree.
3. Anything else is taken as the name of a new branch to create from HEAD.

With no second argument, a new branch named after the worktree is created from HEAD.

wt add feature-auth                                    # Creates .worktrees/feature-auth with branch "feature-auth"
wt add file-assets-phase feature/file-assets-phase     # Attaches existing branch "feature/file-assets-phase"
wt add hotfix main                                     # Creates branch "hotfix" starting from "main"
wt add feat-x origin/main                              # Creates branch "feat-x" starting from (and tracking) origin/main
wt add release-prep v1.0.0                             # Creates branch "release-prep" starting from tag v1.0.0

Branching off a remote needs the worktree name first — wt add feat-x origin/main, not wt add origin/main (and not wt add refs/remotes/origin/main). wt refuses to create any local branch named after a ref: one whose first path segment is a remote name, or one that is a fully qualified refs/... ref. Git resolves refs/heads/ before refs/remotes/, so a local branch called origin/main would shadow the remote-tracking ref and silently redirect every later git log origin/main or git rebase origin/main to a stale commit.

As a start point — the second argument — refs/remotes/origin/main is accepted and equivalent to origin/main.

wt add starts the branch at whatever you last fetched, so git fetch first.

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

wt list

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

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

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

Promote a worktree's branch so it becomes the one checked out in the main working path. The previous main branch is left in place as an ordinary branch (not checked out anywhere), and the promoted worktree directory is removed. Both worktrees must be clean unless --force is used.

wt promote feature-auth
wt promote --force feature-auth  # Promote even with uncommitted changes (may be lost)

Navigate back to the main/original worktree.

wt og

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

wt clean

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.

# 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

• 🚀 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

MIT