Skip to content

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.md
index 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 &#39;-h&#39;)
+<b><span class=g>Automation:</span></b>
+ <b><span class=c>--format</span></b><span class=c> &lt;FORMAT&gt;</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> &lt;path&gt;</span>
Working directory for this command
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 1d96d303f..98772bfb3 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -785,6 +785,16 @@ Options:
-h, --help
Print 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 command
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 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 branch
diff --git a/src/commands/step/promote.rs b/src/commands/step/promote.rs
index 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 operation
pub 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.rs
index 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.rs
index 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.snap
index 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: wt step promote [OPTIONS] [BRANCH]
-h, --help
Print 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 command