worktree-cli

Git worktree manager with automatic env file copying, dependency installation, and editor integration.

Install

curl -fsSL https://raw.githubusercontent.com/bhagyamudgal/worktree-cli/main/install.sh | bash

Or download the binary directly from Releases and place it in your PATH.

Setup

Run this once per repo (it writes .worktreerc and wires up gitignores):

worktree setup                          # interactive: pick base branch + worktree dir
worktree setup --base origin/dev --yes  # non-interactive (scripts/CI)

Then commit the result so teammates get the same defaults:

DEFAULT_BASE=origin/dev

setup asks before adding your worktree directory to the root .gitignore (and always creates <dir>/.gitignore inside it). Only add it by hand if you declined that prompt:

.worktrees/

Usage

worktree setup                                    # configure .worktreerc (interactive)
worktree create feature-auth                    # new branch from configured base
worktree create feature-auth --base main        # override base branch
worktree create feature-auth --editor code      # open in VS Code
worktree create colleague/feature-xyz           # tracks remote branch if it exists
worktree open feature-auth                      # open existing worktree in editor
worktree open feature-auth --editor cursor      # open in Cursor
worktree open feature-auth --editor zed         # open in Zed
worktree list                                   # list all worktrees with status
worktree clean                                  # remove clean, merged worktrees
worktree clean --yes                            # remove without confirmation
worktree remove feature-auth                    # remove worktree + cleanup branch

What it does

On create, the CLI:

1. Fetches latest remote refs
2. Creates a git worktree — if origin/<name> exists, it tracks the remote branch; otherwise branches from --base or DEFAULT_BASE
3. Copies .env and .env.local files from the main repo (searches up to 4 levels deep)
4. Installs dependencies (auto-detects pnpm/yarn/npm/bun)
5. Opens in your editor (VS Code / Cursor / Zed, auto-detected or prompted)

On list, it shows each worktree with:

• Branch name (or "detached")
• Number of changed files
• Commits ahead/behind upstream

On remove, it:

1. Checks for uncommitted changes (prompts before force-removing)
2. Handles broken git references gracefully (falls back to trash if available)
3. Cleans up the local branch
4. Removes empty parent directories

On clean, it:

1. Fetches the latest origin refs and aborts if the fetch fails
2. Finds registered worktrees whose HEAD is merged into the origin default branch
3. Skips worktrees with uncommitted files, except Git-ignored files and .husky/_ internals
4. Previews every eligible worktree and confirms once before removing them
5. Attempts to delete a removed worktree's local branch when one exists, but preserves it if another worktree uses it, its tip changed after verification, or deletion fails; remote branches are never touched

The primary, current, locked, broken, and submodule-bearing worktrees are never removed. Detached and externally located registered worktrees are eligible when their HEAD is merged. Use --yes to bypass the confirmation prompt.

Config

.worktreerc keys are read from one of two locations depending on the key:

Key	Description	Where	Example
DEFAULT_BASE	Default base branch for new worktrees	Project (<repo>/.worktreerc)	origin/dev
WORKTREE_DIR	Directory name for worktrees (default: .worktrees)	Project (<repo>/.worktreerc)	.worktrees
AUTO_UPDATE	Enable background auto-update checks (default: true)	User (~/.worktreerc) only	false

DEFAULT_BASE and WORKTREE_DIR placed in ~/.worktreerc are ignored — worktree reads them from the project file at the repo root only. AUTO_UPDATE placed in a project .worktreerc is ignored with a warning — it must live in ~/.worktreerc so it applies across all repos under your control.

Alias

Add to your ~/.zshrc or ~/.bashrc:

alias gw='worktree'

Then use gw create feature-auth, gw list, etc.

Update

Automatic

Once installed, worktree checks GitHub for a newer release at most once every 24 hours, in the background. When a newer version is found, it is downloaded, verified against a SHA256 hash, and staged. The next time you invoke worktree, the binary is swapped atomically and the command runs against the new version — you'll see a one-line note on stderr.

To disable, create ~/.worktreerc with:

AUTO_UPDATE=false

Or set WORKTREE_NO_UPDATE=1 in your environment (useful in CI).

Auto-update is a no-op when running via bun run dev or in any non-standalone invocation.

Background check failures (network errors, hash mismatches, filesystem issues) are logged to ~/.cache/worktree-cli/last-error — check this file if auto-updates seem stuck.

Manual

worktree update

Forces an immediate check + download + replace, bypassing the 24-hour throttle. Requires write permission to the binary location (use sudo if installed under /usr/local/bin).

Platforms

Pre-built binaries are available for:

• macOS (Apple Silicon / Intel)
• Linux (x64 / ARM64)

Development

Requires Bun 1.4.0.

bun install
bun run dev -- help          # run locally
bun run build                # compile standalone binary
bun run typecheck            # type-check
bun run lint                 # ESLint
bun run format               # Prettier

Releasing

bun changeset

Commit the generated changeset with the user-visible change. Merging it to main opens a chore: version packages pull request. Merging that pull request updates the package version and changelog, builds all platform binaries, and creates the GitHub Release.

CI

Pull requests and pushes to main run lint, format check, and typecheck via GitHub Actions.

License

MIT