Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

11.9 KB
Raw Blame
---
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

Defaults to the current worktree.

Usage: wt remove [OPTIONS] [BRANCHES]...

Arguments:
  [BRANCHES]...
          Branch name or worktree path [default: current]

Options:
      --no-delete-branch
          Keep branch after removal

      --delete-branch
          Delete branch after removal (overrides config [remove] delete-branch = false)

  -D, --force-delete
          Delete unmerged branches

      --foreground
          Run removal in foreground (block until complete)

      --reap
          Kill processes started in the worktree [experimental]
          
          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.

  -f, --force
          Force worktree removal
          
          Remove a dirty worktree, including staged, modified, and untracked files. Without this flag, removal fails if the worktree has any uncommitted changes.

  -h, --help
          Print help (see a summary with '-h')

Automation:
      --no-hooks
          Skip hooks

      --format <FORMAT>
          Output format
          
          JSON prints structured result to stdout after removal completes.
          
          [default: text]
          [possible values: text, json]

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

      --config-set <toml>
          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)

  -v, --verbose...
          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

  -y, --yes
          Skip approval prompts

Examples

Remove current worktree:

  wt remove
  ◎ Running pre-remove project:cleanup
    flyctl scale count 0
  Scaling app to 0 machines
  ◎ Removing api worktree & branch in background (same commit as main, _)
  ○ Switched to worktree for main @ ~/repo

Remove specific worktrees / branches:

  wt remove feature-branch
  wt remove old-feature another-branch

To choose interactively, open the wt switch picker and press Alt-x on a row.

Keep the branch:

  wt remove --no-delete-branch feature-branch

If [remove] delete-branch = false is configured, use --delete-branch to delete a branch for one removal:

  wt remove --delete-branch feature-branch

Force-delete an unmerged branch:

  wt remove -D experimental

Branch cleanup

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. Same commit — Branch HEAD equals the default branch. Shows _ in wt list.
2. Ancestor — Branch is in target's history (fast-forward or rebase case). Shows ⊂.
3. No added changes — Three-dot diff (target...branch) is empty. Shows ⊂.
4. Trees match — Branch tree SHA equals target tree SHA. Shows ⊂.
5. Merge adds nothing — Simulated merge produces the same tree as target. Handles squash-merged branches where target has advanced with changes to different files. Shows ⊂.
6. Patch-id match — 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 ⊂.

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 -D to remove.

The 'same commit' check uses the local default branch; for other checks, 'target' means the default branch, or its upstream (e.g., origin/main) when strictly ahead.

Branches matching these conditions and with empty working trees are dimmed in wt list as safe to delete.

Force flags

Worktrunk has two force flags for different situations:

        Flag          Scope             When to use            
 ─────────────────── ──────── ──────────────────────────────── 
 --force (-f)        Worktree Worktree has uncommitted changes 
 --force-delete (-D) Branch   Branch has unmerged commits      

  wt remove feature --force       # Remove dirty worktree
  wt remove feature -D            # Delete unmerged branch
  wt remove feature --force -D    # Both

Before --force discards uncommitted changes, Worktrunk saves them (except ignored files and changes inside submodules) to refs/wt-backup/<branch> and prints a command to recover them in a new worktree.

Use --no-delete-branch to keep the branch regardless of merge status.

Background removal

Removal runs in the background by default — the command returns immediately, and output goes to .git/wt/logs/{branch}/internal/remove.log. Use --foreground to wait for it.

Reaping processes [experimental]

--reap terminates processes left running in the worktree before it is removed — a post-start 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 (SIGTERM, then SIGKILL for survivors).

  wt remove --reap feature
  ◎ Reaping 2 processes under feature worktree
     ┃ 51234 node
     ┃ 51240 esbuild
  ✓ Reaped 2 processes
  ◎ Removing feature worktree & branch in background (same commit as main, _)

To avoid killing work the user did not mean to kill, two guards keep --reap conservative:

- Interactive processes are spared. A process holding a controlling terminal — an interactive shell, or a terminal editor such as vim with unsaved buffers — is never reaped. Only detached processes remain candidates.
- Discovery is by working directory only. A process that started in the worktree and later changed directory, or a daemon that reparented to init, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with wt step tether, which kills the whole process group when the worktree is removed.

Unix only; on Windows --reap is rejected.

JSON output

--format=json prints one object per removal to stdout: {kind, branch, path, branch_outcome, branch_checked_out_at} for a worktree, with pruned in place of path for a branch-only removal. Branch-only results also include detached_worktree: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or null.

branch_outcome 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                                              
 ──────────────────── ──────────────────────────────────────────────────────────────────────────────────────────────── 
 deleted              The branch is gone                                                                               
 deferred             Left to the background removal, whose result this run doesn't see. --foreground never reports it 
 not_attempted        No deletion was tried: a detached worktree, a sibling checkout, or --no-delete-branch            
 retained_unmerged    Declined: the branch was not integrated into the target                                          
 retained_checked_out Declined: another worktree has the branch checked out                                            
 retained_raced       Declined: the branch moved during the removal. Retry                                             
 retained_failed      The delete command itself failed                                                                 

Hooks

pre-remove hooks run before the worktree is deleted (with access to worktree files). post-remove hooks run after removal. See wt hook for configuration.

Detached HEAD worktrees

Detached worktrees have no branch name. Pass the worktree path instead: wt remove /path/to/worktree.

See also

- wt merge — Remove worktree after merging
- wt list — View all worktrees

----- stderr -----