worktree

A delightful CLI for managing Git worktrees. Stop stashing, start shipping.

Why worktree?

Working on multiple branches simultaneously shouldn't be painful. Git worktrees let you check out multiple branches at once in separate directories, but setting them up manually is tedious: creating the worktree, copying environment files, installing dependencies, opening your editor...

worktree handles all of that with a single command and beautiful interactive prompts.

Features

• Interactive prompts — Guided setup with sensible defaults
• Environment file handling — Automatically symlink or copy your .env files from all directories and subdirectories
• Dependency installation — Detects your package manager and installs dependencies
• Editor integration — Opens your new worktree in Cursor, VS Code, or Zed
• Terminal integration — Option to open the worktree in a new terminal tab
• Smart detection — Knows when you're inside a worktree and offers relevant actions
• Auto-fetch — Fetches latest from origin before creating a worktree
• Update notifications — Keeps you informed about new versions

Installation

# npm
npm install -g @skauffmann/worktree

# bun
bun install -g @skauffmann/worktree

# pnpm
pnpm add -g @skauffmann/worktree

# yarn
yarn global add @skauffmann/worktree

Or run it directly without installing:

# npx
npx @skauffmann/worktree

# bunx
bunx @skauffmann/worktree

Usage

# Start the interactive workflow
worktree

# Pre-fill the branch name
worktree feature/awesome-feature

What happens when you run it?

1. Enter a branch name — Creates the worktree directory named after your branch
2. Fetch latest — Automatically fetches from origin to ensure up-to-date branches
3. Choose branch action — Track an existing remote branch or create a new one
4. Handle environment files — Symlink (recommended) or copy your .env files from all directories and subdirectories
5. Install dependencies — Automatically runs your package manager
6. Open in editor — Jump straight into coding
7. Open in terminal — Optionally open a new terminal tab in the worktree directory

Managing existing worktrees

When you run worktree from inside an existing worktree (or when worktrees exist), you get additional options:

• Create new worktree — Start a new worktree from the current branch or origin/main
• Open — Open the worktree in your editor
• Replace — Delete and recreate the worktree
• Delete — Remove the worktree completely

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | WORKTREE_EDITOR | Editor to open worktrees in (cursor, code, zed) | Auto-detected | | WORKTREE_SKIP_UPDATE_CHECK | Skip the update check on startup | false |

Examples

# Always use VS Code
export WORKTREE_EDITOR=code

# Disable update checks
export WORKTREE_SKIP_UPDATE_CHECK=1

How it works

your-repo/                    # Main repository
├── .git/
├── .env                      # Root environment file
├── apps/
│   └── web/.env              # Nested environment files too!
└── src/

your-repo-feature/            # Worktree created by this CLI
├── .env → ../your-repo/.env              # Symlinked!
├── apps/
│   └── web/.env → ../your-repo/apps/web/.env
└── src/

Worktrees are created as siblings to your main repository, with branch names converted to directory-safe formats (slashes become dashes).

Supported tools

Package managers

The CLI auto-detects your package manager from lock files:

| Lock file | Package manager | |-----------|-----------------| | bun.lockb or bun.lock | bun | | pnpm-lock.yaml | pnpm | | yarn.lock | yarn | | package-lock.json | npm |

If no lock file is found, bun is used by default.

Editors

Editors are auto-detected in this order: Cursor → VS Code → Zed

You can override this with the WORKTREE_EDITOR environment variable.

If no editor is found, the worktree directory opens in your system file explorer.

License

MIT