npm package: @ozeron/wtree
Description: Simplified git worktree management tool
Author: ozeron@me.com
Latest version: 1.0.0

# 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:

```bash
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

```bash
# 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

```bash
# 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`:

```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:

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

Or use an absolute path:

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

### Setup Commands

These run automatically when you create a worktree:

```json
{
  "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:

```json
{
  "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:

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

Create `.cursor/setup-worktree-unix.sh`:
```bash
#!/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:

```json
{
  "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**:
```bash
bun install -g wtree
```

**From source**:
```bash
git clone https://github.com/ozeron/wtree.git
cd wtree
bun link
```

## Requirements

- [Bun](https://bun.sh)
- Git with worktree support (Git 2.5+)

## License

MIT