docs(remove): state that --force discards all uncommitted changes (#2869)

max-sixty · claude · web-flow · commit 89ec4f70faaf · 2026-05-21T18:40:41.000-07:00
The FAQ and the `wt remove --force` help text said `--force` overrides
the untracked-files check "for build artifacts". `--force` actually
removes a dirty worktree including staged and modified *tracked* files,
not just untracked ones (`test_remove_force_with_modified_files`,
`test_remove_force_with_staged_files`). On a destructive command, that
wording can lead users to consent to more data loss than they expected.

Updates the `--force` arg help, the "Force flags" table and example in
`src/cli/mod.rs`, and the FAQ to say `--force` discards staged,
modified, and untracked files; the `help_remove_long` snapshot and the
`remove.md` / `faq.md` doc and skill mirrors are regenerated to match.

&gt; _This was written by Claude Code on behalf of Maximilian Roos_

Co-authored-by: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/docs/content/faq.md b/docs/content/faq.md
@@ -144,7 +144,7 @@ Worktrunk can delete **worktrees** and **branches**. Both have safeguards.
 
 ### Worktree removal
 
-`wt remove` mirrors `git worktree remove`: it refuses to remove worktrees with uncommitted changes (staged, modified, or untracked files). The `--force` flag overrides the untracked-files check for build artifacts that weren't cleaned up.
+`wt remove` mirrors `git worktree remove`: it refuses to remove worktrees with uncommitted changes (staged, modified, or untracked files). The `--force` flag removes the worktree anyway, discarding all of those changes.
 
 For worktrees containing precious ignored data (databases, caches, large assets), use `git worktree lock`:
 
diff --git a/docs/content/remove.md b/docs/content/remove.md
@@ -58,12 +58,12 @@ Worktrunk has two force flags for different situations:
 
 | Flag | Scope | When to use |
 |------|-------|-------------|
-| `--force` (`-f`) | Worktree | Worktree has untracked files |
+| `--force` (`-f`) | Worktree | Worktree has uncommitted changes |
 | `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
 
-{{ terminal(cmd="wt remove feature --force       # Remove worktree with untracked files|||wt remove feature -D            # Delete unmerged branch|||wt remove feature --force -D    # Both") }}
+{{ terminal(cmd="wt remove feature --force       # Remove dirty worktree|||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.
+Without `--force`, removal fails if the worktree has staged, modified, or 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
 
@@ -110,8 +110,8 @@ Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <spa
   <b><span class=c>-f</span></b>, <b><span class=c>--force</span></b>
           Force worktree removal
 
-          Remove worktrees even if they contain untracked files (like build artifacts). Without this
-          flag, removal fails if untracked files exist.
+          Remove a dirty worktree, including staged, modified, and untracked files. Without this
+          flag, removal fails if the worktree has any uncommitted changes.
 
   <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
           Print help (see a summary with &#39;-h&#39;)
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
@@ -430,8 +430,9 @@ pub(crate) struct RemoveArgs {
 
     /// Force worktree removal
     ///
-    /// Remove worktrees even if they contain untracked files (like build
-    /// artifacts). Without this flag, removal fails if untracked files exist.
+    /// Remove a dirty worktree, including staged, modified, and untracked
+    /// files. Without this flag, removal fails if the worktree has any
+    /// uncommitted changes.
     #[arg(short, long)]
     pub(crate) force: bool,
 
@@ -992,16 +993,16 @@ Worktrunk has two force flags for different situations:
 
 | Flag | Scope | When to use |
 |------|-------|-------------|
-| `--force` (`-f`) | Worktree | Worktree has untracked files |
+| `--force` (`-f`) | Worktree | Worktree has uncommitted changes |
 | `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
 
 ```console
-$ wt remove feature --force       # Remove worktree with untracked files
+$ wt remove feature --force       # Remove dirty worktree
 $ 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.
+Without `--force`, removal fails if the worktree has staged, modified, or 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
 
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -11,20 +11,22 @@ info:
     GIT_EDITOR: ""
     LANG: C
     LC_ALL: C
-    LLVM_PROFILE_FILE: /var/folders/v3/8k5q0_6j3_q6gl4h8czr66sh0000gn/T/wt-test-profraw/cov-%m_%p.profraw
+    LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
     NO_COLOR: ""
     PSModulePath: ""
     RUST_LOG: warn
     SHELL: ""
     TERM: alacritty
-    WORKTRUNK_APPROVALS_PATH: /nonexistent/wt/approvals.toml
-    WORKTRUNK_CONFIG_PATH: /nonexistent/wt/config.toml
-    WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
+    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_POWERSHELL_ENV: "0"
@@ -58,7 +60,7 @@ Usage: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[BRANCHES]...[0m
   [1m[36m-f[0m, [1m[36m--force[0m
           Force worktree removal[0m
           
-          Remove worktrees even if they contain untracked files (like build artifacts). Without this flag, removal fails if untracked files exist.[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')
@@ -136,16 +138,16 @@ Branches matching these conditions and with empty working trees are dimmed in [
 
 Worktrunk has two force flags for different situations:
 
-        Flag          Scope           When to use          
- ─────────────────── ──────── ──────────────────────────── 
- [2m--force[0m ([2m-f[0m)        Worktree Worktree has untracked files 
- [2m--force-delete[0m ([2m-D[0m) Branch   Branch has unmerged commits  
+        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 worktree with untracked files[0m[2m[0m
+[107m [0m [2m[0m[2m[34mwt[0m[2m remove feature [0m[2m[36m--force[0m[2m       # Remove dirty worktree[0m[2m[0m
 [107m [0m [2m[0m[2m[34mwt[0m[2m remove feature [0m[2m[36m-D[0m[2m            # Delete unmerged branch[0m[2m[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[2m[0m
 
-Without [2m--force[0m, removal fails if the worktree contains untracked files. Without [2m--force-delete[0m, removal keeps branches with unmerged changes. Use [2m--no-delete-branch[0m to keep the branch regardless of merge status.
+Without [2m--force[0m, removal fails if the worktree has staged, modified, or untracked files. Without [2m--force-delete[0m, removal keeps branches with unmerged changes. Use [2m--no-delete-branch[0m to keep the branch regardless of merge status.
 
 [1m[32mBackground removal[0m
 
