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.mdindex 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`/`tarsync = "{% 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 filtersTemplates 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-startBoth 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.mdindex 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 branchwt 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 alsodiff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 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`/`tarsync = "{% 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 filtersTemplates 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-startBoth 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.mdindex 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 branchwt 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 referencediff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 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 branchwt 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`/`tarsync = "{% 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 filtersTemplates 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-startBoth 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.snapindex 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:[1m[32mBranch cleanup[0m-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., [2morigin/main[0m) when strictly ahead.-Branches showing [2m_[0m or [2m⊂[0m are dimmed as safe to delete.+Branches matching these conditions and with empty working trees are dimmed in [2mwt list[0m as safe to delete.[1m[32mForce flags[0mWorktrunk has two force flags for different situations:- Flag Scope When to use- ─────────────────── ──────── ──────────────────────────────────────────────────────────- [2m--force[0m ([2m-f[0m) Worktree Worktree has untracked files (build artifacts, IDE config)- [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 untracked files+ [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-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-D[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 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.[1m[32mBackground removal[0m@@ -136,7 +136,7 @@ Removal runs in the background by default — the command returns immediately. L[1m[32mDetached HEAD worktrees[0m-Detached worktrees have no branch name. Pass the worktree path instead: [2mwt remove /path/to/worktree[0m. [2mwt switch /path/to/worktree[0m also works.+Detached worktrees have no branch name. Pass the worktree path instead: [2mwt remove /path/to/worktree[0m.[1m[32mSee also[0m