gwt — git worktree manager

A project-agnostic interactive CLI for managing git worktrees. List, create, remove, and jump between worktrees from any repo with a single command.

$ gwt
┌  gwt   git worktree manager
│
◆  What would you like to do?
│  ● List & jump to worktree
│  ○ Create new worktree
│  ○ Remove a worktree
│  ○ Show status across all worktrees
│  ○ Prune stale worktrees
│  ○ Quit
└

Why

git worktree is powerful but verbose. Creating a worktree, jumping into it, checking its status, then removing it without losing work is four commands minimum — each with its own gotchas. gwt wraps the common operations behind a navigable menu, adds safety checks before destructive actions, and makes "jump to worktree" feel like a real cd.

Features

• List & jump — pick a worktree from the list, your shell cds into it.
• Create — from an existing branch, a remote branch, or a brand-new branch (with base picker). Defaults to <repo>/.worktrees/<branch> and offers to gitignore it once.
• Checkout PR — give a PR number (or GitHub URL); fetches pull/<n>/head into a pr-<n> branch and spins up a worktree. If gh CLI is installed, shows the PR title and author before confirming. Works for forks too.
• Remove — warns about uncommitted changes and unmerged commits before deleting; force is opt-in.
• Status — compact table of ahead/behind and dirty count across every worktree.
• Prune — dry-run preview, then clean up stale worktree records.
• Works in any git repo. No config required.

Install

From source (recommended for now)

git clone https://github.com/prabal01/worktree-manager.git
cd worktree-manager
npm install
npm run build
npm link            # exposes `gwt` globally
gwt install-shell   # adds a tiny zsh/bash/fish function so jumping cd's your shell
exec $SHELL         # reload your shell

That's it. Run gwt inside any git repository.

Requirements

• Node.js 18 or newer
• git 2.5+ (worktree support)

Usage

gwt                 # interactive menu
gwt list            # pick a worktree, cd there  (alias: gwt ls)
gwt new             # create a worktree (existing branch or new one)  (alias: gwt add)
gwt new feature/x   # shortcut: create a worktree for branch feature/x
gwt pr              # prompt for a PR number, checkout into a new worktree
gwt pr 123          # shortcut: checkout PR #123
gwt pr https://github.com/owner/repo/pull/123   # accepts URLs too
gwt rm              # remove a worktree with safety checks  (alias: gwt remove)
gwt status          # ahead/behind + dirty across all worktrees
gwt prune           # clean up stale worktree records
gwt install-shell   # (re)install the shell wrapper
gwt --help

Conventions

• Default path: new worktrees go under <repo-root>/.worktrees/<branch> (slashes in branch names become dashes for the path). You can override the path on every create.
• Gitignore: on first create under .worktrees/, you're offered to add the directory to .gitignore. One-time, no surprise edits.
• Safety on remove: uncommitted changes or commits not merged into main/master/develop require explicit force confirmation.

How cd works

A child process can't change its parent shell's working directory, so gwt install-shell writes a small function to your shell rc that wraps the binary:

gwt() {
  local cd_file=$(mktemp -t gwt-cd.XXXXXX)
  GWT_CD_FILE="$cd_file" command gwt "$@"
  local rc=$?
  [ -s "$cd_file" ] && cd "$(cat "$cd_file")"
  rm -f "$cd_file"
  return $rc
}

When you pick a worktree, the binary writes the target path to $GWT_CD_FILE and the wrapper cds into it. If the wrapper isn't installed, the binary prints cd <path> to stderr so you can copy-paste.

Supported shells: zsh (default), bash, fish. The wrapper is idempotent — re-running gwt install-shell won't duplicate it.

Development

npm install
npm run dev         # tsup watch mode → dist/cli.js
npm run typecheck   # tsc --noEmit
npm run build       # one-shot bundle

Source layout:

src/
├── cli.ts                # entry — argv routing
├── menu.ts               # top-level interactive menu
├── git.ts                # thin wrappers over `git worktree …` etc.
├── repo.ts               # find repo root, etc.
├── jump.ts               # write target path for the shell wrapper
├── shell-install.ts      # gwt install-shell
└── commands/             # list, create, remove, status, prune

The binary bundles to a single ~21 KB ESM file with a shebang. No runtime config files, no global state.

Contributing

PRs welcome. Keep changes focused — one feature or fix per PR. Run npm run typecheck && npm run build before submitting.

If you're adding a new command, the pattern is:

1. New file under src/commands/<name>.ts exporting run<Name>().
2. Wire it into src/menu.ts and src/cli.ts.
3. Update the README usage section.

License

MIT © Prabal Saxena