Skip to content

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

docs: clarify --force vs -D flags in wt remove (#565)

Maximilian Roos6ecc51feef36
diff --git a/.claude-plugin/skills/worktrunk/reference/remove.md b/.claude-plugin/skills/worktrunk/reference/remove.md
index 409ab8738..682b181fb 100644
--- a/.claude-plugin/skills/worktrunk/reference/remove.md
+++ b/.claude-plugin/skills/worktrunk/reference/remove.md
@@ -41,19 +41,30 @@ Worktrunk checks five conditions (in order of cost):
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. 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.
+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 showing `_` or `⊂` are dimmed as safe to delete.
-Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.
+## Force flags
-## Background removal
+Worktrunk has two force flags for different situations:
-Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
+| Flag | Scope | When to use |
+|------|-------|-------------|
+| `--force` (`-f`) | Worktree | Worktree has untracked files (build artifacts, IDE config) |
+| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
+
+```bash
+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 `-D`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.
-## Shortcuts
+## Background removal
-`@` (current), `-` (previous), `^` (default branch). See [`wt switch`](https://worktrunk.dev/switch/#shortcuts).
+Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
## Command reference
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 38de82c60..2df5e50db 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -49,19 +49,30 @@ Worktrunk checks five conditions (in order of cost):
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. 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.
+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 showing `_` or `⊂` are dimmed as safe to delete.
-Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.
+## Force flags
-## Background removal
+Worktrunk has two force flags for different situations:
-Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
+| Flag | Scope | When to use |
+|------|-------|-------------|
+| `--force` (`-f`) | Worktree | Worktree has untracked files (build artifacts, IDE config) |
+| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
+
+```bash
+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 `-D`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.
-## Shortcuts
+## Background removal
-`@` (current), `-` (previous), `^` (default branch). See [`wt switch`](@/switch.md#shortcuts).
+Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
## See also
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e5596cfb1..4cc712ecb 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -679,19 +679,30 @@ Worktrunk checks five conditions (in order of cost):
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. 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.
+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 showing `_` or `⊂` are dimmed as safe to delete.
-Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.
+## Force flags
-## Background removal
+Worktrunk has two force flags for different situations:
-Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
+| Flag | Scope | When to use |
+|------|-------|-------------|
+| `--force` (`-f`) | Worktree | Worktree has untracked files (build artifacts, IDE config) |
+| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
-## Shortcuts
+```console
+wt remove feature --force # Remove worktree with untracked files
+wt remove feature -D # Delete unmerged branch
+wt remove feature --force -D # Both
+```
-`@` (current), `-` (previous), `^` (default branch). See [`wt switch`](@/switch.md#shortcuts).
+Without `--force`, removal fails if the worktree contains untracked files. Without `-D`, 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 (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
## See also
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index 20006cd78..a85ed827d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -95,19 +95,28 @@ Worktrunk checks five conditions (in order of cost):
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. 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.
+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 showing _ or ⊂ are dimmed as safe to delete.
-Use -D to force-delete branches with unmerged changes. Use --no-delete-branch to keep the branch regardless of status.
+Force flags
-Background removal
+Worktrunk has two force flags for different situations:
-Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --foreground to run in the foreground.
+ Flag Scope When to use
+ ─────────────────── ──────── ──────────────────────────────────────────────────────────
+ --force (-f) Worktree Worktree has untracked files (build artifacts, IDE config)
+ --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
-Shortcuts
+Without --force, removal fails if the worktree contains untracked files. Without -D, removal keeps branches with unmerged changes. Use --no-delete-branch to keep the branch regardless of merge status.
-@ (current), - (previous), ^ (default branch). See wt switch.
+Background removal
+
+Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --foreground to run in the foreground.
See also