Command reference

wt create

Adds a worktree for <branch>, resolved in order:

With no argument: a clean worktree at the current commit on a new auto-named branch (main-2, main-3, …; current branch recorded as base). Uncommitted changes stay behind — use fork to bring them. The worktree lands at <workspace-root>/<project>/<name> and is seeded with the current worktree's git-ignored files; declared deps copy in the background after the jump.

Refuses when: the repo is not linked; the branch is unknown locally and on every remote; no argument on a detached HEAD (hint: wt fork <name>).

See also: wt fork · wt deps · wt link

wt fork

Forks your current state: a new branch at HEAD, a new worktree, and all your staged, unstaged and untracked changes carried over with the staged/unstaged split preserved exactly. The original worktree is untouched — copy, not move (implemented as git stash create + stash apply --index, plus a file copy for untracked files). Without an argument the branch is auto-named like create.

Passing an existing branch makes it the base instead: wt fork main from a dirty dev cuts an auto-named main-2 at main's tip and applies your changes onto it — "take my WIP onto a fresh main". If the apply isn't clean, the worktree stays with instructions to finish manually.

fork always records the worktree's base branch, so a later argument-less wt reset works. Flags: identical to wt create.

Refuses when: the repo is not linked.

See also: wt create · wt checkout -b · wt root fork

wt checkout (alias: ch)

Jumps to a worktree by directory name (unique prefix works). No git state changes hands — every worktree permanently has its branch checked out.

Bare wt ch opens an interactive picker (terminal only): the 10 most recently used worktrees, newest first. Arrows or j/k move, Enter jumps, Esc/q cancels.

-b <new-branch> works like git checkout -b: fork your current state into a new worktree on that branch and jump there — shorthand for wt fork -c <new-branch>.

See also: wt home · wt switch · wt finish

wt home

Jumps to the main checkout (the root repo) from wherever you are. Equivalent to wt root checkout.

wt switch

Toggles between where you are and where your last wt jump left from — like cd -. Run it twice and you're back. The state is per shell: it lives in the wt() wrapper (handed to the binary as WT_PREV), so every terminal has its own toggle, and the command requires the wrapper.

Refuses when: no previous location exists in this shell (hint: jump somewhere first); the previous directory no longer exists.

wt finish

The "I'm done here" command. Jumps back to the last location this shell jumped from (the same per-shell state switch uses), or home when there is none — and, on request, cleans up on the way out. If the remembered location is inside the worktree being deleted, finish lands you home instead.

Refuses when: -b without -d; run in the main checkout; -d on a base worktree (hint: wt base rm); -d with local changes and no -f.

See also: wt remove · wt switch

wt peek (alias: unpeek)

Exports <rev>'s files (any revision: origin/main, a tag, a sha, HEAD~3) into a disposable fake worktree under ~/worktrees/<project>/peek-… — a plain directory with no branch, no checkout, no git registration — and jumps there. Your real worktrees are never written to, so peeking is safe from any state: dirty, mid-rebase, whatever.

The environment comes along so the peeked code runs: ignored files copy synchronously, declared deps in the background (-w, --no-deps, --no-ignored behave as on create). It is a viewer by contract: git commands inside a peek fail and edits are throwaway. Open peeks appear in bare wt peek and as red peek rows in wt list. If looking turns into working, use wt fork or wt create.

wt root

Runs a command in the root repo's context from wherever you stand; all flags pass through unchanged.

wt global

Works outside any repo, over projects registered with wt link -r. list with no argument prints all registered projects (NAME · WORKTREES · PATH); with a project, that project's full worktree table. status, git-log and checkout behave like their in-repo counterparts, addressed as <project> (the root repo) or <project>/<worktree>.

Project names prefix-match like worktree names. The registry is plain global git config (wt.project.<name> → root repo path); entries whose repo vanished are pruned automatically with a note.

wt base

A base branch is a long-lived branch (main, staging, dev, …) promoted to a permanent, view-only worktree named after the branch: jump in to inspect or run it with zero impact on your real work, and fork off it the moment looking becomes working. Bases sort right after the root in wt list and show orange names.

Drift. wt can't stop git from switching a base's branch — it flags it: a drifted base gets a red BRANCH cell and a ! suffix in wt list, and (base: <name>, drifted) in wt status. wt reset refuses to run inside a base — other worktrees reset to it.

wt list (alias: ls)

wt status

Shows one worktree — current by default, or any by name — as project, worktree (with a (home) marker on the main checkout, base/drift notes on bases), branch, commit, and path fields on stdout. While deps are syncing, a deps line shows the state and log path. Inside a peek, the peek view with its exit hint is shown instead.

-g, --git appends real git status output as if run in that worktree — passthrough, so your git config applies.

wt git-log

Runs plain git log in a worktree without leaving where you stand. The first argument is taken as a worktree name only when it doesn't start with -; everything else passes to git log verbatim, so wt git-log dev --oneline -5 and wt git-log --oneline -5 (current worktree) both do what you'd expect. Passthrough like status -g: your pager, colors and log config all apply.

wt copy

Copies one file into the current worktree — from the root repo by default, or from any worktree via --from (prefix matching). Made for the files git doesn't carry across worktrees: .env, local configs, credentials. Paths are relative to each worktree's root; <dst> defaults to the same relative path. Parent directories are created; symlinks and executable bits survive. An existing destination is refused unless -f overwrites it.

wt deps

Manages deps — heavy git-ignored paths (node_modules, build caches, …) declared once per repo (multi-valued git config wt.deps) and copied into new worktrees by a detached background worker: on create/fork/peek you're already in the new worktree while the dep streams in. Each dep is built in a .wt-partial sibling and renamed into place, so a half-copied directory never appears at its real path. Small ignored files still copy synchronously before the jump.

While a copy runs, wt list shows syncing and wt status a deps line with the log path. wt rm refuses a still-syncing worktree; wt rm -f stops the copier first (its pid rides in the state marker), so a forced removal never races the copy.

sync [<name>] re-copies deps into a worktree in the foreground — recovery after a failed background copy, or onboarding a worktree created before deps were declared (bases included). Related flags on create/fork/peek/base add: -w/--wait, --no-deps, --no-ignored.

wt remove (alias: rm)

Removes a worktree by name (prefix matching).

Refuses when: the worktree is dirty and -f is missing; the target is the main checkout, the worktree you stand in, or a base (hint: wt base rm); deps are still syncing (without -f).

Glob bulk-removal. A pattern (quote it so the shell doesn't expand it) removes several at once: wt rm 'dev-*'. Wildcards only ever match wt-managed worktrees — never the root, bases, other tools' worktrees, or the one you stand in — and always print the matches and ask [y/N] first; only a plain y proceeds. -f/-b apply to every match.

wt reset

Moves the worktree's branch back to the tip of its base branch, staying on the branch. The base is recorded automatically at creation for every fork and for auto-named or remote creates (main-2 remembers main; remote-created worktrees remember origin/<branch>); wt create <branch> from a free local branch records none — there, and for worktrees made by other tools, name the base explicitly: wt reset <branch> always works and overrides the recording.

Local changes block it; --hard proceeds, discarding tracked changes (untracked files are kept — standard git reset --hard semantics).

Refuses when: run in the main checkout; run inside a base worktree (hint: wt base reset snaps a base back to its upstream); no recorded base and no argument.

wt link

Links the repo to a project name, stored in git config wt.name (shared .git/config: visible from every worktree, never tracked, per-clone — a fresh clone needs linking again). The name decides where worktrees live (~/worktrees/<name>/…) and is deliberate, not derived from the directory, so two repos both cloned as app/ don't collide.

create and fork refuse to run in unlinked repos; everything else works regardless. Relinking is allowed — existing worktrees keep working. Unlink with git config --unset wt.name.

-r, --register also adds the project to the global registry that wt global works from. Bare wt link -r registers an already-linked repo — registration is always explicit. With no arguments, shows the current link and whether it is registered.

wt alias

Git-style command aliases: name your favorite invocations and wt expands them, typed arguments appended. add/rm write your global git config (wt.alias.<name>) — aliases are a habit, not a project property — but any scope works: a per-repo alias is just git config wt.alias.stg "status -g".

Builtins always win over an alias of the same name. An alias must expand to a builtin. Aliases tab-complete like the command they expand to, and an alias of a jump command cd's exactly like the real thing.

wt init

Prints the wt() shell function and tab completion for eval in your rc file: eval "$(worktree init zsh)". The function is what makes jumps actually cd (it evals the binary's jump script) and what keeps the per-shell state behind switch/finish.

Completion: subcommands complete on the first word, and everywhere a command accepts an existing worktree or branch name, TAB offers real candidates computed live by the binary (rm only offers what is removable; create also lists remote-only branches). If your .zshrc runs the eval before compinit, wt initializes the completion system itself. The wrapper carries a version marker; an outdated one triggers a stderr warning suggesting a re-eval.

wt prompt

Prints a ready-made <project> (<branch>) prompt segment in pure zsh prompt escapes: the project name instead of the checkout's folder name (unlinked repos fall back to the repo name, non-git directories to the plain path), with the branch colored in the wt list palette — and a red peek:<rev> inside a peek. Literal % in names is escaped, so directory names can't inject prompt codes. One binary call per prompt (~5 ms). zsh only.

wt help / wt --version

make install stamps the version via git describe; building outside a checkout takes make install VERSION=<tag> COMMIT=<sha>.

Internal commands. complete, __jump-alias and __deps-worker exist for tab completion, jump-alias detection and the background deps copier. Implementation details — not for direct use, no compatibility promise.