@wentools/worktree

A CLI for managing git worktree-based workflows — each branch gets its own directory instead of switching in place.

Why

Switching branches in a monorepo means reinstalling dependencies, restarting dev servers, and losing your place. Git worktrees solve this by giving each branch its own checkout, but setting them up by hand is tedious. wt automates the setup, symlinking shared config files and running post-switch commands so new worktrees are ready to use immediately.

Quick start

deno install -g -A jsr:@wentools/worktree    # or: npx @wentools/worktree

wt init [email protected]:org/my-project.git
cd my-project
wt switch my-feature   # creates branch + worktree, prints its path

Commands

wt init <remote> [directory]

Clones the remote as a bare repo, creates the worktrees/ subdirectory, and writes a default .worktree.json config.

wt init [email protected]:org/my-project.git
wt init [email protected]:org/my-project.git custom-name

wt switch <name> [--run-hooks]

Switches to (or creates) a worktree. Can be run from anywhere inside the project tree — it walks up to find the project root.

• If the branch exists (local or remote), checks it out into worktrees/<name>
• If the branch doesn't exist, creates it
• If the worktree already exists, prints its path without recreating it

On new worktrees, symlinks and post-switch hooks run automatically. Pass --run-hooks to re-run hooks on an existing worktree.

Path preservation: If you're inside worktrees/beta/website/src/, switching to main lands you in worktrees/main/website/src/ (if it exists), otherwise the worktree root.

wt switch beta
wt switch my-feature
wt switch main --run-hooks

The switch command prints the target path to stdout. Wrap it in a shell function to cd automatically — see Shell wrapper.

wt remove <name>

Removes a worktree and deletes the branch if it was fully merged.

wt remove my-feature

wt list

Lists all active worktrees.

Shell wrapper

A CLI tool can't change your shell's directory. Add this function to your shell config (.bashrc, .zshrc, etc.) to make switching seamless:

wt() { cd "$(command wt switch "$@")" }

Then just:

wt my-feature    # creates/switches and cd's into the worktree

Config

The .worktree.json file lives in the project root (created by init, edited by hand).

{
  "symlinks": [
    {
      "source": "~/.env/my-project/.env",
      "target": "website/.env"
    }
  ],
  "postSwitch": [
    {
      "command": "pnpm install",
      "workdir": "website"
    }
  ]
}

symlinks

Creates symbolic links inside each new worktree. target is relative to the worktree root. source supports ~ for home directory. Useful for .env files and other gitignored config that won't be present in new checkouts.

postSwitch

Commands to run after a worktree is created. workdir is relative to the worktree root (defaults to the root itself). Commands run in order; if one fails, the rest are skipped.

Install

From JSR (Deno):

deno install -g -A jsr:@wentools/worktree

From npm:

npm install -g @wentools/worktree

License

MIT