Skip to content

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

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

Maximilian Roos89ec4f70faaf
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 289ae98d5..0fe35d267 100644
--- 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
index 4bb1b811f..164215345 100644
--- 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
index 228856d52..2bd0a1f84 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -137,7 +137,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/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index a0009e81b..cb606f87c 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -57,16 +57,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 |
```bash
-$ 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
@@ -108,8 +108,8 @@ Options:
-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.
+ 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')
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index c5b1db164..e20ade71b 100644
--- 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
index 649923c7f..49294c517 100644
--- 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: wt remove [OPTIONS] [BRANCHES]...
-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.
+ 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')
@@ -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
- ─────────────────── ──────── ────────────────────────────
- --force (-f) Worktree Worktree has untracked files
- --force-delete (-D) Branch Branch has unmerged commits
+ 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 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