worktrunk 0.37.1

A CLI for Git worktree management, designed for parallel AI agent workflows
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

---
source: tests/integration_tests/help.rs
info:
  program: wt
  args:
    - remove
    - "--help"
  env:
    CLICOLOR_FORCE: "1"
    COLUMNS: "500"
    GIT_EDITOR: ""
    LANG: C
    LC_ALL: C
    NO_COLOR: ""
    PSModulePath: ""
    RUST_LOG: warn
    SHELL: ""
    TERM: alacritty
    WORKTRUNK_APPROVALS_PATH: /nonexistent/test/approvals.toml
    WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
    WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
    WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
    WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
    WORKTRUNK_TEST_EPOCH: "1735776000"
    WORKTRUNK_TEST_NUSHELL_ENV: "0"
    WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
    WORKTRUNK_TEST_POWERSHELL_ENV: "0"
    WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
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 [default: current]

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

  -D, --force-delete
          Delete unmerged branches

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

  -f, --force
          Force worktree removal
          
          Remove worktrees even if they contain untracked files (like build artifacts). Without this flag, removal fails if untracked files exist.

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

Automation:
  -y, --yes
          Skip approval prompts

      --no-hooks
          Skip hooks

      --format <FORMAT>
          Output format
          
          JSON prints structured result to stdout after removal completes.

          Possible values:
          - text: Human-readable text output
          - json: JSON output
          
          [default: text]

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

      --config <path>
          User config file path

  -v, --verbose...
          Verbose output (-v: info logs + hook/template output; -vv: debug logs + diagnostic report + trace.log/output.log under .git/wt/logs/)

Examples

Remove current worktree:

  wt remove

Remove specific worktrees / branches:

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

Keep the branch:

  wt remove --no-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 (in order of cost):

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 '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 untracked files 
 --force-delete (-D) Branch   Branch has unmerged commits  

  wt remove feature --force       # Remove worktree with untracked files
  wt remove feature -D            # Delete unmerged branch
  wt remove feature --force -D    # Both

Without --force, removal fails if the worktree contains untracked files. Without --force-delete, removal keeps branches with unmerged changes. 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. The worktree is renamed into .git/wt/trash/ (instant same-filesystem rename), git metadata is pruned, the branch is deleted, and a detached rm -rf finishes cleanup. Cross-filesystem worktrees fall back to git worktree remove. Logs: .git/wt/logs/{branch}/internal/remove.log. Use --foreground to run in the foreground.

After each wt remove, entries in .git/wt/trash/ older than 24 hours are swept by a detached rm -rf — eventual cleanup for directories orphaned when a previous background removal was interrupted (SIGKILL, reboot, disk full).

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 -----