Skip to content

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

fix(step): warn when alias shadows a built-in step command (#1389)

Maximilian Roosbf6030b94096
diff --git a/src/commands/alias.rs b/src/commands/alias.rs
index 205875eee..be9041c8f 100644
--- a/src/commands/alias.rs
+++ b/src/commands/alias.rs
@@ -14,7 +14,9 @@ use anyhow::{Context, bail};
use color_print::cformat;
use worktrunk::config::{ProjectConfig, UserConfig, expand_template};
use worktrunk::git::{Repository, WorktrunkError};
-use worktrunk::styling::{eprintln, format_with_gutter, info_message, progress_message};
+use worktrunk::styling::{
+ eprintln, format_with_gutter, info_message, progress_message, warning_message,
+};
use crate::commands::command_approval::approve_alias;
use crate::commands::command_executor::{CommandContext, build_hook_context};
@@ -158,6 +160,28 @@ pub fn step_alias(opts: AliasOptions) -> anyhow::Result<()> {
.unwrap_or_default();
aliases.extend(user_config.aliases(project_id.as_deref()));
+ // Warn about aliases that shadow built-in step commands
+ let shadowed: Vec<_> = aliases
+ .keys()
+ .filter(|k| BUILTIN_STEP_COMMANDS.contains(&k.as_str()))
+ .collect();
+ if !shadowed.is_empty() {
+ let names = shadowed
+ .iter()
+ .map(|k| cformat!("<bold>{k}</>"))
+ .collect::<Vec<_>>()
+ .join(", ");
+ let (noun, verb) = if shadowed.len() == 1 {
+ ("Alias", "shadows a built-in step command")
+ } else {
+ ("Aliases", "shadow built-in step commands")
+ };
+ eprintln!(
+ "{}",
+ warning_message(format!("{noun} {names} {verb} and will never run"))
+ );
+ }
+
let Some(template) = aliases.get(&opts.name) else {
// Check for typos against both built-in commands and aliases
let mut all_candidates: Vec<&str> = BUILTIN_STEP_COMMANDS.to_vec();
diff --git a/tests/integration_tests/step_alias.rs b/tests/integration_tests/step_alias.rs
index f01d17af7..86c9415e8 100644
--- a/tests/integration_tests/step_alias.rs
+++ b/tests/integration_tests/step_alias.rs
@@ -210,6 +210,31 @@ hello = "echo hello"
));
}
+/// Multiple shadowed aliases use plural grammar
+#[rstest]
+fn test_step_alias_shadows_builtin_plural(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+commit = "echo custom-commit"
+rebase = "echo custom-rebase"
+hello = "echo hello"
+"#,
+ );
+ repo.commit("Add alias config");
+ let feature_path = repo.add_worktree("feature");
+
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["nonexistent"],
+ Some(&feature_path),
+ ));
+}
+
/// User config aliases merge with project config aliases
#[rstest]
fn test_step_alias_merge_user_and_project(mut repo: TestRepo) {
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap
index 416b0f9a3..5d828d486 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin.snap
@@ -42,4 +42,5 @@ exit_code: 1
----- stdout -----
----- stderr -----
+▲ Alias commit shadows a built-in step command and will never run
✗ Unknown alias nonexistent (available: hello)
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin_plural.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin_plural.snap
new file mode 100644
index 000000000..7d6164608
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_shadows_builtin_plural.snap
@@ -0,0 +1,46 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - nonexistent
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+▲ Aliases commit, rebase shadow built-in step commands and will never run
+✗ Unknown alias nonexistent (available: hello)