Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(help): compact the aliases section in --help (#2688)
Maximilian Roos1a36910b9467
diff --git a/src/commands/alias.rs b/src/commands/alias.rsindex d12d69012..963ae2a86 100644--- a/src/commands/alias.rs+++ b/src/commands/alias.rs@@ -698,8 +698,8 @@ pub(crate) enum HelpContext {/// 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.+/// `Aliases:` block is a name list plus a shadowed-by-builtin flag and a+/// pointer to `wt config alias show`, none of which has a 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.@@ -716,7 +716,7 @@ pub(crate) fn augment_help(help: &str, context: HelpContext) -> String {// rendered output. The search prefix is derived from the same style// clap uses (our `help_styles().get_header()`), so if the header// styling changes both sides move together.- let aliases_section = render_aliases_section(&aliases, context);+ let aliases_section = render_aliases_help_section(&aliases, context);let options_heading = format!("{}Options:",crate::cli::help_styles().get_header().render()@@ -794,6 +794,69 @@ pub(crate) fn render_aliases_section(out}+/// Format the configured aliases as a compact name list for `wt --help` /+/// `wt step --help`.+///+/// Unlike [`render_aliases_section`] (which `wt config alias show` reuses for+/// the full per-alias listing), this shows only the names — `--help` is for+/// orientation, not inspection. A name that collides with a built-in is+/// flagged inline because the alias never runs via that path; `context`+/// selects which built-ins shadow (see [`HelpContext`]). A name defined in+/// both user and project config still appears once — `wt config alias show+/// <name>` is where the two pipelines are distinguished. Matches clap's+/// "Commands:" styling (bold+green heading, bold+cyan names) so the section+/// blends in. Returns the block without leading or trailing blank lines —+/// the caller positions it.+fn render_aliases_help_section(+ entries: &[(String, CommandConfig, HookSource)],+ context: HelpContext,+) -> String {+ use std::fmt::Write as _;++ let shadowed_names: &[&str] = match context {+ HelpContext::TopLevel => TOP_LEVEL_BUILTINS,+ HelpContext::Step => BUILTIN_STEP_COMMANDS,+ };++ // `entries` is sorted by (name, source); collapse user/project duplicates.+ let mut names: Vec<&str> = Vec::new();+ for (name, _, _) in entries {+ if names.last() != Some(&name.as_str()) {+ names.push(name);+ }+ }++ // `cformat!`'s `</>` emits `\e[39m`, which the markdown pass over this+ // output (`wrap_styled_text`) strips — leaving the fg color dangling onto+ // whatever follows. Terminate each name with a full reset (`\e[0m`, which+ // survives that pass) so the comma separators render uncolored, matching+ // how clap closes each `Commands:` entry.+ let reset = anstyle::Reset;+ let list = names+ .iter()+ .map(|&name| {+ let styled = if shadowed_names.contains(&name) {+ cformat!("<bold><cyan>{name}</></> <yellow>(shadowed by built-in)</>")+ } else {+ cformat!("<bold><cyan>{name}</></>")+ };+ format!("{styled}{reset}")+ })+ .collect::<Vec<_>>()+ .join(", ");++ let mut out = String::new();+ let _ = writeln!(out, "{}", cformat!("<bold><green>Aliases:</></>"));+ // Trailing space after the list: `wrap_styled_text` drops a reset that+ // ends a line, so without a trailing character the last name's color+ // would bleed onto the "Run …" sentence below.+ let _ = write!(+ out,+ " {list} \n\nRun `wt config alias show` for the full definitions."+ );+ out+}+/// Load aliases for display as a flat list sorted by name, with source tagged.////// Duplicate names (same alias in both user and project) appear twice — once@@ -1681,4 +1744,66 @@ test = "cargo test"list ls (shadowed by built-in)");}++ #[test]+ fn test_render_aliases_help_section() {+ // The `--help` block is just a comma-separated name list: user/project+ // duplicates collapse to one entry, a name colliding with a built-in+ // is flagged inline (which built-ins shadow depends on the help+ // context), and a pointer to the full listing follows. There is a+ // trailing space after the list (load-bearing — keeps the last name's+ // color from bleeding onto the "Run …" line; see the function).+ let entries = vec![+ (+ "commit".to_string(),+ cfg_from_toml(r#"cmd = "git commit""#),+ HookSource::User,+ ),+ (+ "deploy".to_string(),+ cfg_from_toml(r#"cmd = "make deploy""#),+ HookSource::User,+ ),+ (+ "list".to_string(),+ cfg_from_toml(r#"cmd = "ls""#),+ HookSource::User,+ ),+ (+ "shared".to_string(),+ cfg_from_toml(r#"cmd = "echo u""#),+ HookSource::User,+ ),+ (+ "shared".to_string(),+ cfg_from_toml(r#"cmd = "echo p""#),+ HookSource::Project,+ ),+ ];+ let mut sorted = entries;+ sorted.sort_by(|a, b| a.0.cmp(&b.0).then(a.2.cmp(&b.2)));++ // Top level: `list` shadows the `wt list` built-in. `commit` is a+ // step-only built-in — `wt commit` still runs the alias.+ insta::assert_snapshot!(+ render_aliases_help_section(&sorted, HelpContext::TopLevel).ansi_strip(),+ @"+ Aliases:+ commit, deploy, list (shadowed by built-in), shared++ Run `wt config alias show` for the full definitions.+ "+ );++ // Under `wt step`: `commit` shadows `wt step commit`; `list` does not.+ insta::assert_snapshot!(+ render_aliases_help_section(&sorted, HelpContext::Step).ansi_strip(),+ @"+ Aliases:+ commit (shadowed by built-in), deploy, list, shared++ Run `wt config alias show` for the full definitions.+ "+ );+ }}diff --git a/src/commands/config/alias.rs b/src/commands/config/alias.rsindex 726d2d543..e5d411d74 100644--- a/src/commands/config/alias.rs+++ b/src/commands/config/alias.rs@@ -2,10 +2,10 @@//!//! Introspection and preview for aliases configured in user config//! (`~/.config/worktrunk/config.toml`) and project config (`.config/wt.toml`).-//! `show` with no name lists every configured alias — the same `Aliases:`-//! block `wt --help` renders, via [`render_aliases_section`]. `show <name>`-//! prints the template text, source-labeled, with one gutter block per alias-//! entry and `# <name>` comment lines above named pipeline steps. `dry-run`+//! `show` with no name lists every configured alias as the `name command`+//! `Aliases:` block, via [`render_aliases_section`]. `show <name>` prints the+//! template text, source-labeled, with one gutter block per alias entry and+//! `# <name>` comment lines above named pipeline steps. `dry-run`//! parses a per-invocation argument vector with the same parser `wt <alias>`//! uses, then expands templates using the same context as execution — so//! previews match what the real run will do. `show <name>` and `dry-run`@@ -79,8 +79,10 @@ pub fn handle_alias_show(name: Option<String>) -> anyhow::Result<()> {Ok(())}-/// List every configured alias as the styled `Aliases:` block — the same-/// listing `wt --help` renders, reused via [`render_aliases_section`].+/// List every configured alias as the styled `name command` `Aliases:`+/// block via [`render_aliases_section`]. `wt --help` shows a more compact+/// names-only variant of the same section (`render_aliases_help_section`)+/// and points here for this fuller listing.////// Tolerates running outside a repository (user-config aliases still list,/// project-config ones are skipped) and outside a config (prints a note).diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_help_includes_aliases.snap b/tests/snapshots/integration__integration_tests__step_alias__step_help_includes_aliases.snapindex 621daa58a..d1c713cb8 100644--- a/tests/snapshots/integration__integration_tests__step_alias__step_help_includes_aliases.snap+++ b/tests/snapshots/integration__integration_tests__step_alias__step_help_includes_aliases.snap@@ -11,10 +11,15 @@ info:COLUMNS: "500"GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMON_DIR: ""GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"GIT_CONFIG_SYSTEM: /dev/null+ GIT_DIR: ""GIT_EDITOR: ""+ GIT_INDEX_FILE: ""+ GIT_OBJECT_DIRECTORY: ""GIT_TERMINAL_PROMPT: "0"+ GIT_WORK_TREE: ""HOME: "[TEST_HOME]"LANG: CLC_ALL: C@@ -30,13 +35,17 @@ info: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_DELAYED_STREAM_MS: "-1"WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_FISH_INSTALLED: "0"WORKTRUNK_TEST_NUSHELL_ENV: "0"WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"---success: true@@ -60,7 +69,9 @@ Usage: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[1m[36mrelocate[0m [experimental] Move worktrees to expected paths[32m[1mAliases:[22m- [36m[1mdeploy[22m make deploy BRANCH={{ branch }}+ [36m[1mdeploy[22m[0m++Run [2mwt config alias show[0m for the full definitions.[1m[32mOptions:[1m[36m-h[0m, [1m[36m--help[0m Print help (see more with '--help')diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_list_with_aliases.snap b/tests/snapshots/integration__integration_tests__step_alias__step_list_with_aliases.snapindex d75b3a576..8ab287625 100644--- a/tests/snapshots/integration__integration_tests__step_alias__step_list_with_aliases.snap+++ b/tests/snapshots/integration__integration_tests__step_alias__step_list_with_aliases.snap@@ -10,10 +10,15 @@ info:COLUMNS: "500"GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMON_DIR: ""GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"GIT_CONFIG_SYSTEM: /dev/null+ GIT_DIR: ""GIT_EDITOR: ""+ GIT_INDEX_FILE: ""+ GIT_OBJECT_DIRECTORY: ""GIT_TERMINAL_PROMPT: "0"+ GIT_WORK_TREE: ""HOME: "[TEST_HOME]"LANG: CLC_ALL: C@@ -29,13 +34,17 @@ info: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_DELAYED_STREAM_MS: "-1"WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_FISH_INSTALLED: "0"WORKTRUNK_TEST_NUSHELL_ENV: "0"WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"---success: true@@ -59,9 +68,9 @@ Usage: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[1m[36mrelocate[0m [experimental] Move worktrees to expected paths[32m[1mAliases:[22m- [36m[1mdeploy[22m make deploy BRANCH={{ branch }}- [36m[1mport[22m echo http://localhost:{{ branch | hash_port }}- [36m[1msquash[22m this shadows the built-in [33m(shadowed by built-in)+ [36m[1mdeploy[22m[0m, [36m[1mport[22m[0m, [36m[1msquash[22m [33m(shadowed by built-in)[0m++Run [2mwt config alias show[0m for the full definitions.[1m[32mOptions:[1m[36m-h[0m, [1m[36m--help[0m Print help (see more with '--help')