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.mdindex 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 referencediff --git a/docs/content/remove.md b/docs/content/remove.mdindex 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 alsodiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 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 alsodiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex 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. [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. Shows [2m⊂[0m.-The "same commit" check uses the local default branch; for other checks, [1mtarget[0m means the default branch, or its upstream (e.g., [2morigin/main[0m) 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., [2morigin/main[0m) when strictly ahead.Branches showing [2m_[0m or [2m⊂[0m are dimmed as safe to delete.-Use [2m-D[0m to force-delete branches with unmerged changes. Use [2m--no-delete-branch[0m to keep the branch regardless of status.+[32mForce flags-[32mBackground removal+Worktrunk has two force flags for different situations:-Removal runs in the background by default (returns immediately). Logs are written to [2m.git/wt-logs/{branch}-remove.log[0m. Use [2m--foreground[0m 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++ [2mwt remove feature --force # Remove worktree with untracked files+ [2mwt remove feature -D # Delete unmerged branch+ [2mwt remove feature --force -D # Both-[32mShortcuts+Without [2m--force[0m, removal fails if the worktree contains untracked files. Without [2m-D[0m, removal keeps branches with unmerged changes. Use [2m--no-delete-branch[0m to keep the branch regardless of merge status.-[2m@[0m (current), [2m-[0m (previous), [2m^[0m (default branch). See [2mwt switch[0m.+[32mBackground removal++Removal runs in the background by default (returns immediately). Logs are written to [2m.git/wt-logs/{branch}-remove.log[0m. Use [2m--foreground[0m to run in the foreground.[32mSee also