quicktree

A CLI tool for easier Git worktree management. Create, list, and prune Git worktrees with automatic directory organization and branch sanitization.

Features

• Automatic worktree creation with sanitized branch names
• Organized directory structure (~/worktrees/<project>-<title>)
• List and prune worktrees with simple commands
• Handles spaces and special characters in titles
• Customizable base directory via QUICKTREE_DIR environment variable

Installation

npm install -g quicktree-cli

Usage

Create a worktree

quicktree "feature xyz"    # Creates ~/worktrees/myproject-feature-xyz
quicktree "Bug Fix #123"   # Creates ~/worktrees/myproject-bug-fix-123

Creates a new worktree at ~/worktrees/<project>-<title> (or $QUICKTREE_DIR/<project>-<title> if set).

Other commands

quicktree --list     # List all worktrees (short: -l)
quicktree --info     # Show available worktrees (compact) (short: -i)
quicktree --prune    # Prune worktrees (short: -p)
quicktree --rm <identifier>    # Remove worktree by identifier (short: -r)
quicktree --remove <identifier> # Remove worktree by identifier (long form)
quicktree --help     # Show help (short: -h)

Examples

# Create worktrees with automatic sanitization
quicktree "Feature XYZ"     # → branch: feature-xyz, dir: myproject-feature-xyz
quicktree "Fix/bug #123"    # → branch: fix-bug-123, dir: myproject-fix-bug-123
quicktree "New Feature!"    # → branch: new-feature, dir: myproject-new-feature

# Remove worktrees by identifier
quicktree --rm feature-xyz  # Remove the Feature XYZ worktree
quicktree -r fix-bug-123    # Remove the Fix/bug #123 worktree (short form)
quicktree --remove new-feature  # Remove the New Feature! worktree (long form)

# Force remove worktrees (skips safety checks)
quicktree --rm feature-xyz --force

# List all worktrees
quicktree -l

# Show available worktrees (compact)
quicktree -i  # Output: Available worktrees: myproject-main, myproject-feature-xyz, myproject-bug-fix

# Clean up stale worktree references
quicktree -p

Configuration

Custom base directory

Set the QUICKTREE_DIR environment variable to change the base directory:

export QUICKTREE_DIR="/path/to/my/worktrees"
quicktree "feature"  # Creates /path/to/my/worktrees/myproject-feature

Auto-show worktrees on directory change

To automatically display available worktrees when entering a Git repository, add the following to your shell configuration:

Bash (~/.bashrc)

cd() {
    builtin cd "$@"
    if git rev-parse --git-dir >/dev/null 2>&1; then
        quicktree -i 2>/dev/null
    fi
}

Zsh (~/.zshrc)

cd() {
    builtin cd "$@"
    if git rev-parse --git-dir >/dev/null 2>&1; then
        quicktree -i 2>/dev/null
    fi
}

Fish (~/.config/fish/config.fish)

function cd
    builtin cd $argv
    if git rev-parse --git-dir >/dev/null 2>&1
        quicktree -i 2>/dev/null
    end
end

Requirements

• Node.js 18.3.0 or higher
• Git repository (must be run from within a Git repository)

License

MIT © David Mohl