wtree

A simple CLI for managing git worktrees. Works great with Cursor IDE.

Why?

Ever been deep in feature work when an urgent bug comes up? Normally you'd have to:

• Stash your changes
• Switch branches
• Fix the bug
• Switch back
• Unstash
• Remember what you were doing...

With worktrees, you just spin up a fresh workspace:

wtree create hotfix/urgent-bug
cd ../worktrees/hotfix/urgent-bug
# Fix bug, commit, push
# Your original work is untouched

Each worktree is a separate working directory for the same repo. No more stashing.

Quick Start

# Run without installing
bunx wtree init
bunx wtree create feature/new-feature

# Or install globally
bun install -g wtree

That's it. Now you have a new worktree at ../worktrees/feature/new-feature ready to go.

Common Commands

# See all your worktrees
wtree list

# Create a new worktree (branches from origin/main by default)
wtree create feature/my-feature

# Emergency hotfix from develop branch
wtree create hotfix/urgent develop

# Done with a worktree? Remove it
wtree close feature/my-feature

# Clean up orphaned worktree entries
wtree prune

# Remove old worktrees based on retention policy
wtree clean --dry-run  # Preview first
wtree clean            # Actually remove them

Configuration

Run wtree init to create worktree.json:

{
  "dir": "../worktrees",
  "setup-worktree": [
    "bun install",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

This tells wtree:

• Where to create worktrees (dir)
• What commands to run after creating one (setup-worktree)

The setup commands are super useful - no more manually running npm install in every new worktree.

Where do worktrees go?

By default: ../worktrees/branch-name/

So if your repo is at /Users/you/code/my-app, worktrees go in /Users/you/code/worktrees/.

You can change this:

{
  "dir": ".."  // Put them directly next to the main repo
}

Or use an absolute path:

{
  "dir": "/tmp/worktrees"  // Temporary location
}

Setup Commands

These run automatically when you create a worktree:

{
  "setup-worktree": [
    "# This is a comment - lines starting with # are skipped",
    "bun install",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "make setup"
  ]
}

$ROOT_WORKTREE_PATH gets replaced with your main repo's path.

OS-Specific Setup

You can define different setup commands for different operating systems:

{
  "dir": "../worktrees",
  "setup-worktree-unix": [
    "bun install",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ],
  "setup-worktree-windows": [
    "npm install",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ],
  "setup-worktree": [
    "echo 'Generic fallback for other OSes'"
  ]
}

Priority: OS-specific config (setup-worktree-unix / setup-worktree-windows) > generic fallback (setup-worktree)

Script Files

Instead of inline commands, you can reference external scripts:

{
  "dir": "../worktrees",
  "setup-worktree-unix": ".cursor/setup-worktree-unix.sh",
  "setup-worktree-windows": ".cursor/setup-worktree-windows.ps1"
}

Create .cursor/setup-worktree-unix.sh:

#!/bin/bash
set -e
bun install
cp "$ROOT_WORKTREE_PATH/.env" .env
echo "Setup complete!"

Make it executable: chmod +x .cursor/setup-worktree-unix.sh

Cleanup Configuration

Automatically remove old worktrees:

{
  "dir": "../worktrees",
  "setup-worktree": ["bun install"],
  "worktree.cleanup.enabled": true,
  "worktree.cleanup.retentionDays": 7,
  "worktree.cleanup.maxSizeGB": 0,
  "worktree.cleanup.intervalHours": 6
}

Options:

• worktree.cleanup.enabled - Enable cleanup (default: false)
• worktree.cleanup.retentionDays - Remove worktrees older than N days (default: 7)
• worktree.cleanup.maxSizeGB - Max total size in GB, 0 = unlimited (default: 0)
• worktree.cleanup.intervalHours - How often to check (default: 6, currently unused)

Note: Cleanup is manual only. Run wtree clean to apply these policies.

How It Works

When you run wtree create feature/my-feature:

1. Branches from origin/main (or origin/master)
2. Creates the worktree in your configured directory
3. Runs your setup commands
4. Done!

Your new worktree is completely clean - even if your current workspace has uncommitted changes. That's the magic of worktrees.

Cursor IDE Support

wtree is fully compatible with Cursor IDE's worktree configuration:

Supported Cursor features:

• ✅ .cursor/worktrees.json auto-detection
• ✅ setup-worktree, setup-worktree-unix, setup-worktree-windows
• ✅ Script file references
• ✅ Cleanup configuration (worktree.cleanup.*)
• ✅ Config search path (worktree-local configs)

What wtree adds:

• Command-line interface for quick worktree management
• Manual cleanup control (no automatic background cleanup)
• Works with worktree.json in addition to .cursor/worktrees.json

Config search order:

1. .cursor/worktrees.json in current worktree (if in a worktree)
2. worktree.json in current worktree
3. .cursor/worktrees.json in repo root
4. worktree.json in repo root

Notes

• wtree close works even without a config file - it'll close any worktree
• You can't accidentally delete your main workspace
• Branches are always created from origin, not your local branch
• Each worktree has its own working directory but shares the same .git folder

Installation

Recommended: Just use bunx wtree - no installation needed.

Global install:

bun install -g wtree

From source:

git clone https://github.com/ozeron/wtree.git
cd wtree
bun link

Requirements

• Bun
• Git with worktree support (Git 2.5+)

License

MIT