Git worktree manager with automatic env file copying, dependency installation, and editor integration.
curl -fsSL https://raw.githubusercontent.com/bhagyamudgal/worktree-cli/main/install.sh | bashOr download the binary directly from Releases and place it in your PATH.
Create a .worktreerc file at your repo root and commit it so teammates get the same defaults:
DEFAULT_BASE=origin/dev
Add .worktrees/ to your .gitignore:
.worktrees/
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 list # list all worktrees with status
worktree remove feature-auth # remove worktree + cleanup branchOn create, the CLI:
- Fetches latest remote refs
- Creates a git worktree — if
origin/<name>exists, it tracks the remote branch; otherwise branches from--baseorDEFAULT_BASE - Copies
.envand.env.localfiles from the main repo (searches up to 4 levels deep) - Installs dependencies (auto-detects pnpm/yarn/npm/bun)
- Opens in your editor (VS Code / Cursor, 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:
- Checks for uncommitted changes (prompts before force-removing)
- Handles broken git references gracefully (falls back to
trashif available) - Cleans up the local branch
- Removes empty parent directories
.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.
Add to your ~/.zshrc or ~/.bashrc:
alias gw='worktree'Then use gw create feature-auth, gw list, etc.
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=falseOr 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.
worktree updateForces 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).
Pre-built binaries are available for:
- macOS (Apple Silicon / Intel)
- Linux (x64 / ARM64)
Requires Bun.
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# 1. Update version in package.json
# 2. Update CHANGELOG.md
# 3. Commit, then run:
./release.shThis tags the version and pushes to trigger GitHub Actions, which builds binaries for all platforms and creates a GitHub Release.
Pull requests and pushes to main run lint, format check, and typecheck via GitHub Actions.
MIT