Skip to content

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.rs
index 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.rs
index 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.snap
index 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: C
LC_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: wt step [OPTIONS] <COMMAND>
relocate [experimental] Move worktrees to expected paths
Aliases:
- deploy make deploy BRANCH={{ branch }}
+ deploy
+
+Run wt config alias show for the full definitions.
Options:
-h, --help 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.snap
index 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: C
LC_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: wt step [OPTIONS] <COMMAND>
relocate [experimental] Move worktrees to expected paths
Aliases:
- deploy make deploy BRANCH={{ branch }}
- port echo http://localhost:{{ branch | hash_port }}
- squash this shadows the built-in (shadowed by built-in)
+ deploy, port, squash (shadowed by built-in)
+
+Run wt config alias show for the full definitions.
Options:
-h, --help Print help (see more with '--help')