Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(step promote): add --format text|json flag (parity with rebase/push/etc.) (#3424)
Chris Chen0b42d42670d6
diff --git a/docs/content/step.md b/docs/content/step.mdindex 69952b0f3..5ba08da6e 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -755,6 +755,16 @@ Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>Print help (see a summary with '-h')+<b><span class=g>Automation:</span></b>+ <b><span class=c>--format</span></b><span class=c> <FORMAT></span>+ Output format++ JSON prints structured result to stdout after the promote completes. The mismatch warning+ still appears on stderr in JSON mode (safety signal).++ [default: text]+ [possible values: text, json]+<b><span class=g>Global Options:</span></b><b><span class=c>-C</span></b><span class=c> <path></span>Working directory for this commanddiff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 1d96d303f..98772bfb3 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -785,6 +785,16 @@ Options:-h, --helpPrint help (see a summary with '-h')+Automation:+ --format <FORMAT>+ Output format++ JSON prints structured result to stdout after the promote completes. The mismatch warning+ still appears on stderr in JSON mode (safety signal).++ [default: text]+ [possible values: text, json]+Global Options:-C <path>Working directory for this commanddiff --git a/src/cli/step.rs b/src/cli/step.rsindex c3d474cb9..737e45c63 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -576,6 +576,13 @@ The swap uses `rename()` for each entry — fast regardless of entry size, since/// Defaults to current branch, or default branch from main worktree.#[arg(add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]branch: Option<String>,++ /// Output format+ ///+ /// JSON prints structured result to stdout after the promote completes.+ /// The mismatch warning still appears on stderr in JSON mode (safety signal).+ #[arg(long, default_value = "text", help_heading = "Automation")]+ format: crate::cli::SwitchFormat,},/// \[experimental\] Remove worktrees merged into the default branchdiff --git a/src/commands/step/promote.rs b/src/commands/step/promote.rsindex 4f306902d..de3f6e27c 100644--- a/src/commands/step/promote.rs+++ b/src/commands/step/promote.rs@@ -154,8 +154,17 @@ fn distribute_staged(/// Result of a promote operationpub enum PromoteResult {- /// Branch was promoted successfully- Promoted,+ /// Branch was promoted successfully.+ ///+ /// `mismatch` is `true` when the promote did not restore canonical state+ /// (i.e. the target branch is not the default branch). Consumers can use+ /// this to detect that the safety warning was printed.+ Promoted {+ target: String,+ main_branch: String,+ swapped: usize,+ mismatch: bool,+ },/// Already in canonical state (requested branch is already in main)AlreadyInMain(String),}@@ -399,7 +408,9 @@ pub fn handle_promote(branch: Option<&str>) -> anyhow::Result<PromoteResult> {0};- // Print success messages only after everything succeeded+ // Print success messages only after everything succeeded. These go to+ // stderr regardless of --format, matching `rebase`/`push`: the human+ // status line is stderr, the JSON envelope on stdout is unaffected.eprintln!("{}",success_message(cformat!(@@ -415,7 +426,12 @@ pub fn handle_promote(branch: Option<&str>) -> anyhow::Result<PromoteResult> {);}- Ok(PromoteResult::Promoted)+ Ok(PromoteResult::Promoted {+ target: target_branch,+ main_branch,+ swapped,+ mismatch: !is_restoring,+ })}#[cfg(test)]diff --git a/src/main.rs b/src/main.rsindex 26f4a7397..ca6e8676d 100644--- a/src/main.rs+++ b/src/main.rs@@ -378,18 +378,37 @@ fn handle_step_command(),StepCommand::Eval { template, format } => step_eval(&template, format),StepCommand::ForEach { format, args } => step_for_each(args, format),- StepCommand::Promote { branch } => {- handle_promote(branch.as_deref()).map(|result| match result {- commands::PromoteResult::Promoted => (),- commands::PromoteResult::AlreadyInMain(branch) => {- eprintln!(- "{}",- info_message(cformat!(- "Branch <bold>{branch}</> is already in main worktree"- ))- );- }- })+ StepCommand::Promote { branch, format } => {+ let result = handle_promote(branch.as_deref())?;+ if format == SwitchFormat::Json {+ let output = match &result {+ commands::PromoteResult::Promoted {+ target,+ main_branch,+ swapped,+ mismatch,+ } => serde_json::json!({+ "outcome": "promoted",+ "target": target,+ "main_branch": main_branch,+ "swapped": swapped,+ "mismatch": mismatch,+ }),+ commands::PromoteResult::AlreadyInMain(branch) => serde_json::json!({+ "outcome": "already_in_main",+ "branch": branch,+ }),+ };+ println!("{}", serde_json::to_string_pretty(&output)?);+ } else if let commands::PromoteResult::AlreadyInMain(branch) = &result {+ eprintln!(+ "{}",+ info_message(cformat!(+ "Branch <bold>{branch}</> is already in main worktree"+ ))+ );+ }+ Ok(())}StepCommand::Prune {dry_run,diff --git a/tests/integration_tests/step_promote.rs b/tests/integration_tests/step_promote.rsindex 2eb884cbc..e90b74644 100644--- a/tests/integration_tests/step_promote.rs+++ b/tests/integration_tests/step_promote.rs@@ -964,3 +964,99 @@ fn test_promote_detached_head_linked(mut repo: TestRepo) {Some(&feature_path),));}++/// `step promote --format=json` reports `already_in_main` when target branch is+/// already in the main worktree, mirroring `step rebase --format=json` shape.+#[rstest]+fn test_promote_already_in_main_json(mut repo: TestRepo) {+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();+ let _feature_path = repo.add_worktree("feature");++ // 'main' is already in main worktree+ let output = repo+ .wt_command()+ .args(["step", "promote", "main", "--format=json"])+ .current_dir(repo.root_path())+ .output()+ .unwrap();+ assert!(output.status.success());+ let parsed: serde_json::Value =+ serde_json::from_slice(&output.stdout).expect("valid JSON to stdout");+ assert_eq!(parsed["outcome"], "already_in_main");+ assert_eq!(parsed["branch"], "main");+}++/// `step promote --format=json` reports `promoted` with target, main_branch,+/// swapped count, and mismatch flag when a feature branch is promoted.+#[rstest]+fn test_promote_swap_json(mut repo: TestRepo) {+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();+ let _feature_path = repo.add_worktree_with_commit("feature", "f.txt", "x", "feat: x");++ let output = repo+ .wt_command()+ .args(["step", "promote", "feature", "--format=json"])+ .current_dir(repo.root_path())+ .output()+ .unwrap();+ assert!(+ output.status.success(),+ "promote failed: {}",+ String::from_utf8_lossy(&output.stderr)+ );+ let parsed: serde_json::Value =+ serde_json::from_slice(&output.stdout).expect("valid JSON to stdout");+ assert_eq!(parsed["outcome"], "promoted");+ assert_eq!(parsed["target"], "feature");+ assert_eq!(parsed["main_branch"], "main");+ assert_eq!(parsed["swapped"], 0);+ assert_eq!(parsed["mismatch"], true);++ // The mismatch warning still appears on stderr even in JSON mode (safety signal).+ let stderr = String::from_utf8_lossy(&output.stderr);+ assert!(+ stderr.contains("mismatched worktree state"),+ "expected mismatch warning on stderr, got: {stderr}"+ );+ // The "Promoted:" success line also goes to stderr in JSON mode, matching+ // `rebase`/`push`: the human status line is stderr, the JSON on stdout is+ // the machine-readable signal.+ assert!(+ stderr.contains("Promoted:"),+ "expected promote success line on stderr, got: {stderr}"+ );+}++/// `step promote --format=json` reports `mismatch: false` when restoring the+/// default branch back to the main worktree.+#[rstest]+fn test_promote_restore_json(mut repo: TestRepo) {+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();+ let feature_path = repo.add_worktree("feature");++ // First promote creates mismatch (main now has feature)+ repo.wt_command()+ .args(["step", "promote", "feature"])+ .output()+ .unwrap();++ // Now restore — promote the default branch (main) back+ let output = repo+ .wt_command()+ .args(["step", "promote", "main", "--format=json"])+ .current_dir(&feature_path)+ .output()+ .unwrap();+ assert!(+ output.status.success(),+ "restore failed: {}",+ String::from_utf8_lossy(&output.stderr)+ );+ let parsed: serde_json::Value =+ serde_json::from_slice(&output.stdout).expect("valid JSON to stdout");+ assert_eq!(parsed["outcome"], "promoted");+ assert_eq!(parsed["target"], "main");+ assert_eq!(parsed["main_branch"], "feature");+ assert_eq!(parsed["swapped"], 0);+ assert_eq!(parsed["mismatch"], false);+}diff --git a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap b/tests/snapshots/integration__integration_tests__help__help_step_promote.snapindex 1bb3a4ccb..6cfbfcc01 100644--- a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap+++ b/tests/snapshots/integration__integration_tests__help__help_step_promote.snap@@ -49,6 +49,15 @@ Usage: [1m[36mwt step promote[0m [36m[OPTIONS][0m [36m[BRANCH][0m[1m[36m-h[0m, [1m[36m--help[0mPrint help (see a summary with '-h')+[1m[32mAutomation:[0m+ [1m[36m--format[0m[36m [0m[36m<FORMAT>[0m+ Output format[0m++ JSON prints structured result to stdout after the promote completes. The mismatch warning still appears on stderr in JSON mode (safety signal).[0m++ [default: text]+ [possible values: text, json]+[1m[32mGlobal Options:[0m[1m[36m-C[0m[36m [0m[36m<path>[0mWorking directory for this command