Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
---
source: tests/integration_tests/help.rs
info:
program: wt
args:
- remove
- "--help"
env:
CLICOLOR_FORCE: "1"
COLUMNS: "500"
GIT_ALLOW_PROTOCOL: file
GIT_CONFIG_COUNT: "2"
GIT_CONFIG_GLOBAL: /nonexistent/wt/gitconfig
GIT_CONFIG_KEY_0: user.useConfigOnly
GIT_CONFIG_KEY_1: rerere.enabled
GIT_CONFIG_SYSTEM: /nonexistent/wt/gitconfig
GIT_CONFIG_VALUE_0: "true"
GIT_CONFIG_VALUE_1: "false"
LANG: C
LC_ALL: C
LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
TERM: alacritty
WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
WORKTRUNK_TEST_BASH_INSTALLED: "0"
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
WORKTRUNK_TEST_CODEX_INSTALLED: "0"
WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
WORKTRUNK_TEST_EPOCH: "1735776000"
WORKTRUNK_TEST_FISH_INSTALLED: "0"
WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
WORKTRUNK_TEST_PARENT_SHELL: ""
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_PROBE_TIMEOUT_MS: "60000"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
WORKTRUNK_TEST_ZSH_INSTALLED: "0"
---
success: true
exit_code: 0
----- stdout -----
wt remove - Remove worktree; delete branch if merged[0m
Defaults to the current worktree.[0m
Usage: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[BRANCHES]...[0m
[1m[32mArguments:[0m
[36m[BRANCHES]...[0m
Branch name or worktree path [default: current]
[1m[32mOptions:[0m
[1m[36m--no-delete-branch[0m
Keep branch after removal
[1m[36m--delete-branch[0m
Delete branch after removal (overrides config [1m[remove] delete-branch = false[0m)
[1m[36m-D[0m, [1m[36m--force-delete[0m
Delete unmerged branches
[1m[36m--foreground[0m
Run removal in foreground (block until complete)
[1m[36m--reap[0m
Kill processes started in the worktree [experimental][0m
Before removal, terminate processes whose working directory is under the worktree — dev servers, watchers, language servers. Processes holding a controlling terminal (interactive shells, terminal editors) are left alone. Unix only.[0m
[1m[36m-f[0m, [1m[36m--force[0m
Force worktree removal[0m
Remove a dirty worktree, including staged, modified, and untracked files. Without this flag, removal fails if the worktree has any uncommitted changes.[0m
[1m[36m-h[0m, [1m[36m--help[0m
Print help (see a summary with '-h')
[1m[32mAutomation:[0m
[1m[36m--no-hooks[0m
Skip hooks
[1m[36m--format[0m[36m [0m[36m<FORMAT>[0m
Output format[0m
JSON prints structured result to stdout after removal completes.[0m
[default: text]
[possible values: text, json]
[1m[32mGlobal Options:[0m
[1m[36m-C[0m[36m [0m[36m<path>[0m
Working directory for this command
[1m[36m--config[0m[36m [0m[36m<path>[0m
User config file path
[1m[36m--config-set[0m[36m [0m[36m<toml>[0m
Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
[1m[36m-v[0m, [1m[36m--verbose[0m[36m...[0m
Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach
[1m[36m-y[0m, [1m[36m--yes[0m
Skip approval prompts
[1m[32mExamples[0m
Remove current worktree:
[107m [0m [2m[0m[2m[34mwt[0m[2m remove[0m
[107m [0m [2m[0m[2m[34m◎[0m[2m Running pre-remove project:cleanup[0m
[107m [0m [2m [0m[2m[34mflyctl[0m[2m scale count 0[0m
[107m [0m [2m[0m[2m[34mScaling[0m[2m app to 0 machines[0m
[107m [0m [2m[0m[2m[34m◎[0m[2m Removing api worktree & [0m[2m[34mbranch[0m[2m in background ([0m[2m[34msame[0m[2m commit as main, _)[0m
[107m [0m [2m[0m[2m[34m○[0m[2m Switched to worktree for main @ ~/repo[0m
Remove specific worktrees / branches:
[107m [0m [2m[0m[2m[34mwt[0m[2m remove feature-branch[0m
[107m [0m [2m[0m[2m[34mwt[0m[2m remove old-feature another-branch[0m
To choose interactively, open the [2mwt switch[0m picker and press [2mAlt-x[0m on a row.
Keep the branch:
[107m [0m [2m[0m[2m[34mwt[0m[2m remove [0m[2m[36m--no-delete-branch[0m[2m feature-branch[0m
If [2m[remove] delete-branch = false[0m is configured, use [2m--delete-branch[0m to delete a branch for one removal:
[107m [0m [2m[0m[2m[34mwt[0m[2m remove [0m[2m[36m--delete-branch[0m[2m feature-branch[0m
Force-delete an unmerged branch:
[107m [0m [2m[0m[2m[34mwt[0m[2m remove [0m[2m[36m-D[0m[2m experimental[0m
[1m[32mBranch cleanup[0m
By default, branches are deleted when they would add no changes to the default branch if merged. This works with both unchanged git histories, and squash-merge or rebase workflows where commit history differs but file changes match.
Worktrunk checks six conditions:
1. [1mSame commit[0m — Branch HEAD equals the default branch. Shows [2m_[0m in [2mwt list[0m.
2. [1mAncestor[0m — Branch is in target's history (fast-forward or rebase case). Shows [2m⊂[0m.
3. [1mNo added changes[0m — Three-dot diff ([2mtarget...branch[0m) is empty. Shows [2m⊂[0m.
4. [1mTrees match[0m — Branch tree SHA equals target tree SHA. Shows [2m⊂[0m.
5. [1mMerge adds nothing[0m — Simulated merge produces the same tree as target. Handles squash-merged branches where target has advanced with changes to different files. Shows [2m⊂[0m.
6. [1mPatch-id match[0m — Branch's entire diff matches a single squash-merge commit on target. Fallback for when the simulated merge conflicts because target later modified the same files the branch touched. Shows [2m⊂[0m.
The default-branch walk is capped so a single check stays fast; a squash merge with hundreds of commits landed since the merge point falls outside the cap and needs [2m-D[0m to remove.
The 'same commit' check uses the local default branch; for other checks, 'target' means the default branch, or its upstream (e.g., [2morigin/main[0m) when strictly ahead.
Branches matching these conditions and with empty working trees are dimmed in [2mwt list[0m as safe to delete.
[1m[32mForce flags[0m
Worktrunk has two force flags for different situations:
Flag Scope When to use
─────────────────── ──────── ────────────────────────────────
[2m--force[0m ([2m-f[0m) Worktree Worktree has uncommitted changes
[2m--force-delete[0m ([2m-D[0m) Branch Branch has unmerged commits
[107m [0m [2m[0m[2m[34mwt[0m[2m remove feature [0m[2m[36m--force[0m[2m # Remove dirty worktree[0m
[107m [0m [2m[0m[2m[34mwt[0m[2m remove feature [0m[2m[36m-D[0m[2m # Delete unmerged branch[0m
[107m [0m [2m[0m[2m[34mwt[0m[2m remove feature [0m[2m[36m--force[0m[2m [0m[2m[36m-D[0m[2m # Both[0m
Before [2m--force[0m discards uncommitted changes, Worktrunk saves them (except ignored files and changes inside submodules) to [2mrefs/wt-backup/<branch>[0m and prints a command to recover them in a new worktree.
Use [2m--no-delete-branch[0m to keep the branch regardless of merge status.
[1m[32mBackground removal[0m
Removal runs in the background by default — the command returns immediately, and output goes to [2m.git/wt/logs/{branch}/internal/remove.log[0m. Use [2m--foreground[0m to wait for it.
[1m[32mReaping processes [experimental][0m
[2m--reap[0m terminates processes left running in the worktree before it is removed — a [2mpost-start[0m dev server, a file watcher, a language server — freeing the ports and file handles they hold. Processes are discovered by working directory: any process whose current directory is at or under the worktree path ([2mSIGTERM[0m, then [2mSIGKILL[0m for survivors).
[107m [0m [2m[0m[2m[34mwt[0m[2m remove [0m[2m[36m--reap[0m[2m feature[0m
[107m [0m [2m[0m[2m[34m◎[0m[2m Reaping 2 processes under feature worktree[0m
[107m [0m [2m [0m[2m[34m┃[0m[2m 51234 node[0m
[107m [0m [2m [0m[2m[34m┃[0m[2m 51240 esbuild[0m
[107m [0m [2m[0m[2m[34m✓[0m[2m Reaped 2 processes[0m
[107m [0m [2m[0m[2m[34m◎[0m[2m Removing feature worktree & [0m[2m[34mbranch[0m[2m in background ([0m[2m[34msame[0m[2m commit as main, _)[0m
To avoid killing work the user did not mean to kill, two guards keep [2m--reap[0m conservative:
- [1mInteractive processes are spared.[0m A process holding a controlling terminal — an interactive shell, or a terminal editor such as [2mvim[0m with unsaved buffers — is never reaped. Only detached processes remain candidates.
- [1mDiscovery is by working directory only.[0m A process that started in the worktree and later changed directory, or a daemon that reparented to [2minit[0m, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with [2mwt step tether[0m, which kills the whole process group when the worktree is removed.
Unix only; on Windows [2m--reap[0m is rejected.
[1m[32mJSON output[0m
[2m--format=json[0m prints one object per removal to stdout: [2m{kind, branch, path, branch_outcome, branch_checked_out_at}[0m for a worktree, with [2mpruned[0m in place of [2mpath[0m for a branch-only removal. Branch-only results also include [2mdetached_worktree[0m: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or [2mnull[0m.
[2mbranch_outcome[0m names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:
Value Meaning
──────────────────── ────────────────────────────────────────────────────────────────────────────────────────────────
[2mdeleted[0m The branch is gone
[2mdeferred[0m Left to the background removal, whose result this run doesn't see. [2m--foreground[0m never reports it
[2mnot_attempted[0m No deletion was tried: a detached worktree, a sibling checkout, or [2m--no-delete-branch[0m
[2mretained_unmerged[0m Declined: the branch was not integrated into the target
[2mretained_checked_out[0m Declined: another worktree has the branch checked out
[2mretained_raced[0m Declined: the branch moved during the removal. Retry
[2mretained_failed[0m The delete command itself failed
[1m[32mHooks[0m
[2mpre-remove[0m hooks run before the worktree is deleted (with access to worktree files). [2mpost-remove[0m hooks run after removal. See [2mwt hook[0m for configuration.
[1m[32mDetached HEAD worktrees[0m
Detached worktrees have no branch name. Pass the worktree path instead: [2mwt remove /path/to/worktree[0m.
[1m[32mSee also[0m
- [2mwt merge[0m — Remove worktree after merging
- [2mwt list[0m — View all worktrees
----- stderr -----