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.mdindex 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.mdindex 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.rsindex 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.rsindex 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() {