Skip to content

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

docs: tighten remove and hook help text (#1765)

Maximilian Roosa4fe57b5108e
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 417ddb84f..bab6381a7 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -220,15 +220,6 @@ Some variables are conditional: `upstream` requires remote tracking; `base`/`tar
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
```
-### Migration from earlier versions
-
-`worktree_path` changed meaning in two hook types:
-
-- **pre-switch** (existing worktrees): previously the source worktree, now the destination. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the source.
-- **post-merge**: previously the merge target worktree, now the feature worktree (active). Use `{{ target_worktree_path }}` or `{{ cwd }}` for where code landed.
-
-New variables `cwd`, `target_worktree_path`, `base`, and `base_worktree_path` are available in more hook types than before.
-
## Worktrunk filters
Templates support Jinja2 filters for transforming values:
@@ -370,14 +361,14 @@ Pipelines matter when there's a dependency chain — typically setup steps that
# Designing Effective Hooks
-## post-start vs pre-start
+## pre-start vs post-start
Both run when creating a worktree. The difference:
| Hook | Execution | Best for |
|------|-----------|----------|
-| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
| `pre-start` | Blocks until complete | Tasks the developer needs before working (dependency install) |
+| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 94aaeed0a..d458c9da4 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -40,7 +40,7 @@ wt remove -D experimental
## Branch cleanup
-By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.
+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 five conditions (in order of cost):
@@ -52,7 +52,7 @@ Worktrunk checks five conditions (in order of cost):
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.
+Branches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.
## Force flags
@@ -60,7 +60,7 @@ Worktrunk has two force flags for different situations:
| Flag | Scope | When to use |
|------|-------|-------------|
-| `--force` (`-f`) | Worktree | Worktree has untracked files (build artifacts, IDE config) |
+| `--force` (`-f`) | Worktree | Worktree has untracked files |
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
```bash
@@ -69,7 +69,7 @@ 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.
+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
@@ -81,7 +81,7 @@ Removal runs in the background by default — the command returns immediately. L
## Detached HEAD worktrees
-Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`. `wt switch /path/to/worktree` also works.
+Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`.
## See also
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index e06e38dd1..b9bb56ae5 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -211,15 +211,6 @@ Some variables are conditional: `upstream` requires remote tracking; `base`/`tar
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
```
-### Migration from earlier versions
-
-`worktree_path` changed meaning in two hook types:
-
-- **pre-switch** (existing worktrees): previously the source worktree, now the destination. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the source.
-- **post-merge**: previously the merge target worktree, now the feature worktree (active). Use `{{ target_worktree_path }}` or `{{ cwd }}` for where code landed.
-
-New variables `cwd`, `target_worktree_path`, `base`, and `base_worktree_path` are available in more hook types than before.
-
## Worktrunk filters
Templates support Jinja2 filters for transforming values:
@@ -361,14 +352,14 @@ Pipelines matter when there's a dependency chain — typically setup steps that
# Designing Effective Hooks
-## post-start vs pre-start
+## pre-start vs post-start
Both run when creating a worktree. The difference:
| Hook | Execution | Best for |
|------|-----------|----------|
-| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
| `pre-start` | Blocks until complete | Tasks the developer needs before working (dependency install) |
+| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index 3ce99b956..14cfe0cc1 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -31,7 +31,7 @@ wt remove -D experimental
## Branch cleanup
-By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.
+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 five conditions (in order of cost):
@@ -43,7 +43,7 @@ Worktrunk checks five conditions (in order of cost):
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.
+Branches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.
## Force flags
@@ -51,7 +51,7 @@ Worktrunk has two force flags for different situations:
| Flag | Scope | When to use |
|------|-------|-------------|
-| `--force` (`-f`) | Worktree | Worktree has untracked files (build artifacts, IDE config) |
+| `--force` (`-f`) | Worktree | Worktree has untracked files |
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
```bash
@@ -60,7 +60,7 @@ 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.
+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
@@ -72,7 +72,7 @@ Removal runs in the background by default — the command returns immediately. L
## Detached HEAD worktrees
-Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`. `wt switch /path/to/worktree` also works.
+Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`.
## Command reference
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 5a8c80786..87903ef17 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -777,7 +777,7 @@ wt remove -D experimental
## Branch cleanup
-By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.
+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 five conditions (in order of cost):
@@ -789,7 +789,7 @@ Worktrunk checks five conditions (in order of cost):
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.
+Branches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.
## Force flags
@@ -797,7 +797,7 @@ Worktrunk has two force flags for different situations:
| Flag | Scope | When to use |
|------|-------|-------------|
-| `--force` (`-f`) | Worktree | Worktree has untracked files (build artifacts, IDE config) |
+| `--force` (`-f`) | Worktree | Worktree has untracked files |
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
```console
@@ -806,7 +806,7 @@ 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.
+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
@@ -818,7 +818,7 @@ Removal runs in the background by default — the command returns immediately. L
## Detached HEAD worktrees
-Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`. `wt switch /path/to/worktree` also works.
+Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`.
## See also
@@ -1310,15 +1310,6 @@ Some variables are conditional: `upstream` requires remote tracking; `base`/`tar
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
```
-### Migration from earlier versions
-
-`worktree_path` changed meaning in two hook types:
-
-- **pre-switch** (existing worktrees): previously the source worktree, now the destination. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the source.
-- **post-merge**: previously the merge target worktree, now the feature worktree (active). Use `{{ target_worktree_path }}` or `{{ cwd }}` for where code landed.
-
-New variables `cwd`, `target_worktree_path`, `base`, and `base_worktree_path` are available in more hook types than before.
-
## Worktrunk filters
Templates support Jinja2 filters for transforming values:
@@ -1458,14 +1449,14 @@ Pipelines matter when there's a dependency chain — typically setup steps that
# Designing Effective Hooks
-## post-start vs pre-start
+## pre-start vs post-start
Both run when creating a worktree. The difference:
| Hook | Execution | Best for |
|------|-----------|----------|
-| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
| `pre-start` | Blocks until complete | Tasks the developer needs before working (dependency install) |
+| `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |
Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
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 7cb1c8906..74dd8e662 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -97,7 +97,7 @@ Force-delete an unmerged branch:
Branch cleanup
-By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.
+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 five conditions (in order of cost):
@@ -109,22 +109,22 @@ Worktrunk checks five conditions (in order of cost):
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.
+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 (build artifacts, IDE config)
- --force-delete (-D) Branch Branch has unmerged commits
+ 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 -D, 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 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
@@ -136,7 +136,7 @@ Removal runs in the background by default — the command returns immediately. L
Detached HEAD worktrees
-Detached worktrees have no branch name. Pass the worktree path instead: wt remove /path/to/worktree. wt switch /path/to/worktree also works.
+Detached worktrees have no branch name. Pass the worktree path instead: wt remove /path/to/worktree.
See also