Skip to content

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

docs(step): move aliases section after subcommands (#1502)

Maximilian Roos6048546e3a34
diff --git a/docs/content/step.md b/docs/content/step.md
index 970d9d158..c33f0e8e9 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -42,28 +42,6 @@ wt step push
- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
- [`<alias>`](#aliases) — [experimental] Run a configured command alias
-## Aliases
-
-Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.
-
-```toml
-# .config/wt.toml
-[aliases]
-deploy = "make deploy BRANCH={{ branch }}"
-port = "echo http://localhost:{{ branch | hash_port }}"
-```
-
-```bash
-wt step deploy # run the alias
-wt step deploy --dry-run # show expanded command
-wt step deploy --var env=staging # pass extra template variables
-wt step deploy --yes # skip approval prompt
-```
-
-When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](@/hook.md#security) on first run (same as project hooks). User-config aliases are trusted.
-
-Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
-
## See also
- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
@@ -708,4 +686,26 @@ Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</spa
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+## Aliases
+
+[experimental] Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+port = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+```bash
+wt step deploy # run the alias
+wt step deploy --dry-run # show expanded command
+wt step deploy --var env=staging # pass extra template variables
+wt step deploy --yes # skip approval prompt
+```
+
+When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](@/hook.md#security) on first run (same as project hooks). User-config aliases are trusted.
+
+Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
+
<!-- END AUTO-GENERATED from `wt step --help-page` -->
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index f10f092a0..4d50c2332 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -33,28 +33,6 @@ wt step push
- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
- [`<alias>`](#aliases) — [experimental] Run a configured command alias
-## Aliases
-
-Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](https://worktrunk.dev/hook/#template-variables) as hooks.
-
-```toml
-# .config/wt.toml
-[aliases]
-deploy = "make deploy BRANCH={{ branch }}"
-port = "echo http://localhost:{{ branch | hash_port }}"
-```
-
-```bash
-wt step deploy # run the alias
-wt step deploy --dry-run # show expanded command
-wt step deploy --var env=staging # pass extra template variables
-wt step deploy --yes # skip approval prompt
-```
-
-When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](https://worktrunk.dev/hook/#security) on first run (same as project hooks). User-config aliases are trusted.
-
-Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
-
## Command reference
wt step - Run individual operations
@@ -677,3 +655,25 @@ Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</spa
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Verbose output (-v: hooks, templates; -vv: debug report)
+
+## Aliases
+
+[experimental] Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](https://worktrunk.dev/hook/#template-variables) as hooks.
+
+```toml
+# .config/wt.toml
+[aliases]
+deploy = "make deploy BRANCH={{ branch }}"
+port = "echo http://localhost:{{ branch | hash_port }}"
+```
+
+```bash
+wt step deploy # run the alias
+wt step deploy --dry-run # show expanded command
+wt step deploy --var env=staging # pass extra template variables
+wt step deploy --yes # skip approval prompt
+```
+
+When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](https://worktrunk.dev/hook/#security) on first run (same as project hooks). User-config aliases are trusted.
+
+Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index a7f28d0e3..a482ad2f5 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1051,9 +1051,21 @@ wt step push
- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
- [`<alias>`](#aliases) — [experimental] Run a configured command alias
+## See also
+
+- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- [`wt hook`](@/hook.md) — Run configured hooks
+
+<!-- subdoc: commit -->
+<!-- subdoc: squash -->
+<!-- subdoc: diff -->
+<!-- subdoc: copy-ignored -->
+<!-- subdoc: for-each -->
+<!-- subdoc: prune -->
+<!-- subdoc: relocate -->
## Aliases
-Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.
+[experimental] Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](@/hook.md#template-variables) as hooks.
```toml
# .config/wt.toml
@@ -1071,19 +1083,7 @@ wt step deploy --yes # skip approval prompt
When defined in both user and project config, user aliases take precedence. Project-config aliases require [command approval](@/hook.md#security) on first run (same as project hooks). User-config aliases are trusted.
-Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
-
-## See also
-
-- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
-- [`wt hook`](@/hook.md) — Run configured hooks
-<!-- subdoc: commit -->
-<!-- subdoc: squash -->
-<!-- subdoc: diff -->
-<!-- subdoc: copy-ignored -->
-<!-- subdoc: for-each -->
-<!-- subdoc: prune -->
-<!-- subdoc: relocate -->"#
+Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run."#
)]
Step {
#[command(subcommand)]
diff --git a/src/help.rs b/src/help.rs
index eac6740de..e76734446 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -328,6 +328,7 @@ Commands with pages: merge, switch, remove, list"
// Subdocs are expanded separately so main Command reference comes first
let parent_name = format!("wt {}", subcommand);
let raw_help = combine_command_docs(sub);
+ let raw_help = raw_help.replace("```console\n", "```bash\n");
// Split content at first subdoc placeholder
let subdoc_marker = "<!-- subdoc:";
@@ -339,8 +340,7 @@ Commands with pages: merge, switch, remove, list"
// Process main content (before subdocs)
let main_help = {
- let text = main_content.replace("```console\n", "```bash\n");
- let text = expand_demo_placeholders(&text);
+ let text = expand_demo_placeholders(main_content);
colorize_ci_status_for_html(&text)
};
@@ -520,6 +520,7 @@ fn format_subcommand_section(
// Get combined docs: about + subtitle + after_long_help
let raw_help = combine_command_docs(sub);
+ let raw_help = raw_help.replace("```console\n", "```bash\n");
// Split content at first subdoc placeholder so command reference comes before nested subdocs
let subdoc_marker = "<!-- subdoc:";
@@ -531,8 +532,7 @@ fn format_subcommand_section(
// Process main content (before any nested subdocs)
let main_help = {
- let text = main_content.replace("```console\n", "```bash\n");
- let text = increase_heading_levels(&text);
+ let text = increase_heading_levels(main_content);
colorize_ci_status_for_html(&text)
};
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index e389ab9c1..780e19f78 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -90,9 +90,14 @@ Manual merge workflow with review between steps:
- relocate — [experimental] Move worktrees to expected paths
- <alias> — [experimental] Run a configured command alias
+See also
+
+- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- wt hook — Run configured hooks
+
Aliases
-Custom command templates configured in user config (~/.config/worktrunk/config.toml) or project config (.config/wt.toml). Aliases support the same template variables as hooks.
+[experimental] Custom command templates configured in user config (~/.config/worktrunk/config.toml) or project config (.config/wt.toml). Aliases support the same template variables as hooks.
  # .config/wt.toml
  [aliases]
@@ -107,8 +112,3 @@ Custom command templates configured in user config (~/.config/worktrunk/conf
When defined in both user and project config, user aliases take precedence. Project-config aliases require command approval on first run (same as project hooks). User-config aliases are trusted.
Alias names that match a built-in step command (commit, squash, etc.) are shadowed by the built-in and will never run.
-
-See also
-
-- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
-- wt hook — Run configured hooks