Skip to content

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

docs: explain why aliases and hooks render --help differently (#2318)

Maximilian Roos566f39933183
diff --git a/docs/content/extending.md b/docs/content/extending.md
index e46412cf0..7a76fdbca 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -203,7 +203,7 @@ Hooks and aliases share a template-variable model and a smart-routing rule for `
| Approval skip flag | Post-subcommand `--yes` / `-y` supported (`wt hook pre-merge --yes`) | Only the global form (`wt -y <alias>`); post-alias `--yes` falls through to `{{ args }}` |
| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax |
| Force-bind escape | `--var KEY=VALUE` (deprecated — prefer `--KEY=VALUE` — but still force-binds) | None — smart routing is the only path |
-| `--help` | Clap-rendered per hook type (`wt hook --help`, `wt hook pre-merge --help`) | `wt <alias> --help` redirects to `wt config alias show` / `dry-run` |
+| `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation — `wt <alias> --help` redirects to `wt config alias show` / `dry-run`; `wt --help` and `wt step --help` list configured aliases alongside built-in commands |
| Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |
| Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 7390a692d..2ef1486f8 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -210,7 +210,7 @@ Hooks and aliases share a template-variable model and a smart-routing rule for `
| Approval skip flag | Post-subcommand `--yes` / `-y` supported (`wt hook pre-merge --yes`) | Only the global form (`wt -y <alias>`); post-alias `--yes` falls through to `{{ args }}` |
| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax |
| Force-bind escape | `--var KEY=VALUE` (deprecated — prefer `--KEY=VALUE` — but still force-binds) | None — smart routing is the only path |
-| `--help` | Clap-rendered per hook type (`wt hook --help`, `wt hook pre-merge --help`) | `wt <alias> --help` redirects to `wt config alias show` / `dry-run` |
+| `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation — `wt <alias> --help` redirects to `wt config alias show` / `dry-run`; `wt --help` and `wt step --help` list configured aliases alongside built-in commands |
| Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |
| Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |
diff --git a/src/commands/alias.rs b/src/commands/alias.rs
index f5a3c4724..b6099a0fd 100644
--- a/src/commands/alias.rs
+++ b/src/commands/alias.rs
@@ -604,6 +604,12 @@ pub(crate) enum HelpContext {
/// `arg_required_else_help`), all of which flow through clap's `DisplayHelp`
/// error. Tolerates running outside a repository: user-config aliases still
/// list, project-config aliases just get skipped.
+///
+/// This is the help-rendering counterpart to `inject_hook_subcommands` for
+/// aliases. Hooks use Command-tree injection because they have a fixed
+/// schema clap can render faithfully; aliases use text-splicing because the
+/// template body is the content, and the `Aliases:` block carries display
+/// signals (source marker, shadowed-by-builtin) that have no clap analogue.
pub(crate) fn augment_help(help: &str, context: HelpContext) -> String {
// Help must not emit deprecation/unknown-field warnings or write `.new`
// migration files as a side effect of rendering the alias list.
diff --git a/src/completion.rs b/src/completion.rs
index 3a0a5a3b1..7951f1c58 100644
--- a/src/completion.rs
+++ b/src/completion.rs
@@ -503,6 +503,17 @@ fn build_hook_completion_command(name: &'static str) -> Command {
/// `step_alias`). Aliases that shadow a built-in at a given level are skipped
/// for that level only — `commit` is shadowed under `step` but offered at the
/// top level, since `wt commit` runs the alias.
+///
+/// Unlike `inject_hook_subcommands`, this is intentionally *not* called from
+/// `help.rs`. Hooks have a fixed clap-expressible argument schema; aliases
+/// don't — `AliasOptions::parse` routes `--KEY=VALUE` based on which template
+/// vars the alias references, `--dry-run` is rejected, post-alias `--yes`
+/// forwards to `{{ args }}`. A clap stub is a useful approximation for
+/// completion but would misrepresent alias semantics on a `--help` page. The
+/// help-path counterparts are `augment_help` (text-splices the `Aliases:`
+/// section into `wt --help` / `wt step --help`, preserving source markers and
+/// shadowed-by-builtin annotations) and `emit_alias_help_hint` (redirects
+/// `wt <alias> --help` to `wt config alias show` / `dry-run`).
fn inject_alias_subcommands(cmd: Command) -> Command {
let aliases = load_aliases_for_completion();
if aliases.is_empty() {