Skip to content

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

feat(alias): support `--key=value` shorthand for alias variables (#2091)

Maximilian Roos5b89ef3b99b3
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 98c30b284..8167cbb7e 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -111,7 +111,7 @@ deploy = "make deploy BRANCH={{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
```
-{{ terminal(cmd="wt step deploy|||wt step deploy --dry-run|||wt step deploy --var env=staging") }}
+{{ terminal(cmd="wt step deploy|||wt step deploy --dry-run|||wt step deploy --env=staging") }}
An `up` alias that fetches all remotes and rebases each worktree onto its upstream:
diff --git a/docs/content/step.md b/docs/content/step.md
index 0a3a694b1..0972a7c5e 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -822,7 +822,7 @@ deploy = "make deploy BRANCH={{ branch }}"
port = "echo http://localhost:{{ branch | hash_port }}"
```
-{{ terminal(cmd="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") }}
+{{ terminal(cmd="wt step deploy # run the alias|||wt step deploy --dry-run # show expanded command|||wt step deploy --env=staging # pass template variable|||wt step deploy --var env=staging # equivalent long form|||wt step deploy --yes # skip approval prompt") }}
Multi-line aliases work too. This `up` alias fetches all remotes and rebases each worktree onto its upstream, skipping worktrees without a tracking branch or with a rebase already in progress:
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 3f886a533..288ab7a5c 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -107,7 +107,7 @@ open = "open http://localhost:{{ branch | hash_port }}"
```bash
$ wt step deploy
$ wt step deploy --dry-run
-$ wt step deploy --var env=staging
+$ wt step deploy --env=staging
```
An `up` alias that fetches all remotes and rebases each worktree onto its upstream:
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 1080d83ea..a76d8b582 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -870,7 +870,8 @@ 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 --env=staging # pass template variable
+$ wt step deploy --var env=staging # equivalent long form
$ wt step deploy --yes # skip approval prompt
```
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index a84e003f9..56abed938 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1160,7 +1160,8 @@ port = "echo http://localhost:{{ branch | hash_port }}"
```console
$ 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 --env=staging # pass template variable
+$ wt step deploy --var env=staging # equivalent long form
$ wt step deploy --yes # skip approval prompt
```
diff --git a/src/commands/alias.rs b/src/commands/alias.rs
index c6e42f233..b2108b430 100644
--- a/src/commands/alias.rs
+++ b/src/commands/alias.rs
@@ -70,7 +70,12 @@ impl AliasOptions {
/// Parse alias options from the external subcommand args.
///
/// First element is the alias name, remaining are flags:
- /// `--dry-run`, `--yes`/`-y`, and `--var KEY=VALUE`.
+ /// `--dry-run`, `--yes`/`-y`, `--var KEY=VALUE`, or `--KEY=VALUE`.
+ ///
+ /// Unknown `--key=value` flags are treated as template variable assignments,
+ /// so `--env=staging` is equivalent to `--var env=staging`. The `=` is
+ /// required — bare `--key` flags (without a value) are rejected. Use
+ /// `--var KEY=VALUE` if a variable name collides with a built-in flag.
pub fn parse(args: Vec<String>) -> anyhow::Result<Self> {
let Some(name) = args.first().cloned() else {
bail!("Missing alias name");
@@ -96,6 +101,19 @@ impl AliasOptions {
let pair = parse_var(arg.strip_prefix("--var=").unwrap())?;
vars.push(pair);
}
+ arg if arg.starts_with("--") => {
+ let rest = &arg[2..];
+ if let Some((key, value)) = rest.split_once('=') {
+ if key.is_empty() {
+ bail!("Variable name must not be empty (got '--={value}')");
+ }
+ vars.push((key.to_string(), value.to_string()));
+ } else {
+ bail!(
+ "Unknown flag '{arg}' for alias '{name}' (use --{rest}=VALUE to pass a variable)"
+ );
+ }
+ }
other => {
bail!("Unexpected argument '{other}' for alias '{name}'");
}
@@ -492,6 +510,66 @@ mod tests {
],
}
"#);
+ // --key=value shorthand
+ assert_debug_snapshot!(parse(&["deploy", "--env=staging"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ dry_run: false,
+ yes: false,
+ vars: [
+ (
+ "env",
+ "staging",
+ ),
+ ],
+ }
+ "#);
+ // --key=value with equals in value
+ assert_debug_snapshot!(parse(&["deploy", "--url=http://host?a=1"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ dry_run: false,
+ yes: false,
+ vars: [
+ (
+ "url",
+ "http://host?a=1",
+ ),
+ ],
+ }
+ "#);
+ // --key=value mixed with --var and flags
+ assert_debug_snapshot!(parse(&["deploy", "--env=prod", "--var", "region=us-east", "--dry-run"]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ dry_run: true,
+ yes: false,
+ vars: [
+ (
+ "env",
+ "prod",
+ ),
+ (
+ "region",
+ "us-east",
+ ),
+ ],
+ }
+ "#);
+ // --key= (empty value)
+ assert_debug_snapshot!(parse(&["deploy", "--env="]).unwrap(), @r#"
+ AliasOptions {
+ name: "deploy",
+ dry_run: false,
+ yes: false,
+ vars: [
+ (
+ "env",
+ "",
+ ),
+ ],
+ }
+ "#);
}
#[test]
@@ -500,9 +578,10 @@ mod tests {
assert_snapshot!(parse(&[]).unwrap_err(), @"Missing alias name");
assert_snapshot!(parse(&["deploy", "--var"]).unwrap_err(), @"--var requires a KEY=VALUE argument");
assert_snapshot!(parse(&["deploy", "--var", "noequals"]).unwrap_err(), @"--var value must be KEY=VALUE");
- assert_snapshot!(parse(&["deploy", "--verbose"]).unwrap_err(), @"Unexpected argument '--verbose' for alias 'deploy'");
+ assert_snapshot!(parse(&["deploy", "--verbose"]).unwrap_err(), @"Unknown flag '--verbose' for alias 'deploy' (use --verbose=VALUE to pass a variable)");
assert_snapshot!(parse(&["deploy", "arg1"]).unwrap_err(), @"Unexpected argument 'arg1' for alias 'deploy'");
assert_snapshot!(parse(&["deploy", "--var", "=value"]).unwrap_err(), @"--var key must not be empty (got '=value')");
+ assert_snapshot!(parse(&["deploy", "--=value"]).unwrap_err(), @"Variable name must not be empty (got '--=value')");
}
#[test]
diff --git a/tests/integration_tests/step_alias.rs b/tests/integration_tests/step_alias.rs
index 91b4c26d5..f93116ea6 100644
--- a/tests/integration_tests/step_alias.rs
+++ b/tests/integration_tests/step_alias.rs
@@ -143,6 +143,29 @@ greet = "echo Hello {{ name }} from {{ branch }}"
));
}
+/// --key=value shorthand for --var key=value
+#[rstest]
+fn test_step_alias_with_shorthand_var(mut repo: TestRepo) {
+ repo.write_project_config(
+ r#"
+[aliases]
+greet = "echo Hello {{ name }} from {{ branch }}"
+"#,
+ );
+ 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",
+ &["greet", "--dry-run", "--name=World", "--yes"],
+ Some(&feature_path),
+ ));
+}
+
/// Alias command failure propagates exit code (--yes bypasses approval)
#[rstest]
fn test_step_alias_exit_code(mut repo: TestRepo) {
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 d3510bc4e..2a454b1eb 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -109,7 +109,8 @@ Custom command templates configured in user config (~/.config/worktrunk/conf
  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 --env=staging # pass template variable
+  wt step deploy --var env=staging # equivalent long form
  wt step deploy --yes # skip approval prompt
Multi-line aliases work too. This up alias fetches all remotes and rebases each worktree onto its upstream, skipping worktrees without a tracking branch or with a rebase already in progress:
diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_with_shorthand_var.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_with_shorthand_var.snap
new file mode 100644
index 000000000..7b0730d85
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_with_shorthand_var.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/step_alias.rs
+info:
+ program: wt
+ args:
+ - step
+ - greet
+ - "--dry-run"
+ - "--name=World"
+ - "--yes"
+ 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: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ 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_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Alias greet would run:
+  echo Hello World from feature