Skip to content

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

Add experimental `wt step promote` command (#789)

Maximilian Roosbc2ee2dcb6e3
diff --git a/docs/content/step.md b/docs/content/step.md
index 914e36740..874410604 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -36,6 +36,7 @@ wt step push
- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
+- `promote` — [experimental] Put a branch into the main worktree
- `relocate` — [experimental] Move worktrees to expected paths
## See also
@@ -61,6 +62,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=c>diff</span></b> Show all changes since branching
<b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
<b><span class=c>for-each</span></b> [experimental] Run command in each worktree
+ <b><span class=c>promote</span></b> [experimental] Put a branch into the main worktree
<b><span class=c>relocate</span></b> [experimental] Move worktrees to expected paths
<b><span class=g>Options:</span></b>
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index e63597cd2..f89e8c752 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -28,6 +28,7 @@ wt step push
- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
+- `promote` — [experimental] Put a branch into the main worktree
- `relocate` — [experimental] Move worktrees to expected paths
## Command reference
@@ -47,6 +48,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=c>diff</span></b> Show all changes since branching
<b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
<b><span class=c>for-each</span></b> [experimental] Run command in each worktree
+ <b><span class=c>promote</span></b> [experimental] Put a branch into the main worktree
<b><span class=c>relocate</span></b> [experimental] Move worktrees to expected paths
<b><span class=g>Options:</span></b>
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index bd7d40175..a20712877 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1027,6 +1027,7 @@ wt step push
- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
+- `promote` — [experimental] Put a branch into the main worktree
- `relocate` — [experimental] Move worktrees to expected paths
## See also
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 82f6d0f84..58125b12c 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -372,6 +372,57 @@ Note: This command is experimental and may change in future versions.
args: Vec<String>,
},
+ /// \[experimental\] Put a branch into the main worktree
+ ///
+ /// The displaced branch moves to the promoted branch's worktree.
+ #[command(
+ after_long_help = r#"**Experimental.** Use promote for temporary testing when the main worktree has special significance (Docker Compose, IDE configs, heavy build artifacts anchored to project root), and hooks & tools aren't yet set up to run on arbitrary worktrees. The idiomatic Worktrunk workflow does not use `promote`; instead each worktree has a full environment. `promote` is the only Worktrunk command which changes a branch in an existing worktree.
+
+## Example
+
+```console
+# from ~/project (main worktree)
+$ wt step promote feature
+```
+
+Before:
+
+```
+ Branch Path
+@ main ~/project
++ feature ~/project.feature
+```
+
+After:
+
+```
+ Branch Path
+@ feature ~/project
++ main ~/project.feature
+```
+
+To restore: `wt step promote main` from anywhere, or just `wt step promote` from the main worktree.
+
+Without an argument, promotes the current branch — or restores the default branch if run from the main worktree.
+
+## Requirements
+
+- Both worktrees must be clean
+- The branch must have an existing worktree
+
+## Gitignored files
+
+Gitignored files are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. See [copy-ignored](/step/#copy-ignored) for filtering with `.worktreeinclude`.
+"#
+ )]
+ Promote {
+ /// Branch to promote to main worktree
+ ///
+ /// Defaults to current branch, or default branch from main worktree.
+ #[arg(add = crate::completion::worktree_only_completer())]
+ branch: Option<String>,
+ },
+
/// \[experimental\] Move worktrees to expected paths
///
/// Relocates worktrees whose path doesn't match the `worktree-path` template.
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index a80ec81c7..9b4aece34 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -40,8 +40,8 @@ pub(crate) use merge::{MergeOptions, handle_merge};
#[cfg(unix)]
pub(crate) use select::handle_select;
pub(crate) use step_commands::{
- RebaseResult, SquashResult, handle_rebase, handle_squash, step_commit, step_copy_ignored,
- step_diff, step_relocate, step_show_squash_prompt,
+ PromoteResult, RebaseResult, SquashResult, handle_promote, handle_rebase, handle_squash,
+ step_commit, step_copy_ignored, step_diff, step_relocate, step_show_squash_prompt,
};
pub(crate) use worktree::{
OperationMode, handle_remove, handle_remove_current, is_worktree_at_expected_path,
diff --git a/src/commands/step_commands.rs b/src/commands/step_commands.rs
index b6a3a1973..640b24d01 100644
--- a/src/commands/step_commands.rs
+++ b/src/commands/step_commands.rs
@@ -1,12 +1,15 @@
-//! Step commands for the merge workflow.
+//! Step commands for the merge workflow and standalone worktree utilities.
//!
-//! This module contains the individual steps that make up `wt merge`:
+//! Merge steps:
//! - `step_commit` - Commit working tree changes
//! - `handle_squash` - Squash commits into one
//! - `step_show_squash_prompt` - Show squash prompt without executing
//! - `handle_rebase` - Rebase onto target branch
//! - `step_diff` - Show all changes since branching
+//!
+//! Standalone:
//! - `step_copy_ignored` - Copy gitignored files matching .worktreeinclude
+//! - `handle_promote` - Put a branch into the main worktree
use std::fs;
use std::io::ErrorKind;
@@ -21,7 +24,7 @@ use worktrunk::git::Repository;
use worktrunk::path::format_path_for_display;
use worktrunk::styling::{
eprintln, format_with_gutter, hint_message, info_message, progress_message, success_message,
- verbosity,
+ verbosity, warning_message,
};
use super::command_approval::approve_hooks;
@@ -537,6 +540,52 @@ pub fn step_diff(target: Option<&str>, extra_args: &[String]) -> anyhow::Result<
Ok(())
}
+/// List gitignored entries in a worktree, filtered by `.worktreeinclude` and excluding
+/// entries that contain nested worktrees.
+///
+/// Combines three steps:
+/// 1. `list_ignored_entries()` — git ls-files for ignored entries
+/// 2. `.worktreeinclude` filtering — only matching entries if the file exists
+/// 3. Nested worktree filtering — exclude entries containing other worktrees
+fn list_and_filter_ignored_entries(
+ worktree_path: &Path,
+ context: &str,
+ worktree_paths: &[PathBuf],
+) -> anyhow::Result<Vec<(PathBuf, bool)>> {
+ let ignored_entries = list_ignored_entries(worktree_path, context)?;
+
+ // Filter to entries that match .worktreeinclude (or all if no file exists)
+ let include_path = worktree_path.join(".worktreeinclude");
+ let filtered: Vec<_> = if include_path.exists() {
+ let include_matcher = {
+ let mut builder = GitignoreBuilder::new(worktree_path);
+ if let Some(err) = builder.add(&include_path) {
+ return Err(worktrunk::git::GitError::WorktreeIncludeParseError {
+ error: err.to_string(),
+ }
+ .into());
+ }
+ builder.build().context("Failed to build include matcher")?
+ };
+ ignored_entries
+ .into_iter()
+ .filter(|(path, is_dir)| include_matcher.matched(path, *is_dir).is_ignore())
+ .collect()
+ } else {
+ ignored_entries
+ };
+
+ // Filter out entries that contain other worktrees
+ Ok(filtered
+ .into_iter()
+ .filter(|(entry_path, _)| {
+ !worktree_paths
+ .iter()
+ .any(|wt_path| wt_path != worktree_path && wt_path.starts_with(entry_path))
+ })
+ .collect())
+}
+
/// Handle `wt step copy-ignored` command
///
/// Copies gitignored files from a source worktree to a destination worktree.
@@ -595,49 +644,13 @@ pub fn step_copy_ignored(
return Ok(());
}
- // Get ignored entries from git
- // --directory stops at directory boundaries (avoids listing thousands of files in target/)
- let ignored_entries = list_ignored_entries(&source_path, &source_context)?;
-
- // Filter to entries that match .worktreeinclude (or all if no file exists)
- let include_path = source_path.join(".worktreeinclude");
- let entries_to_copy: Vec<_> = if include_path.exists() {
- // Build include matcher from .worktreeinclude
- let include_matcher = {
- let mut builder = GitignoreBuilder::new(&source_path);
- if let Some(err) = builder.add(&include_path) {
- return Err(worktrunk::git::GitError::WorktreeIncludeParseError {
- error: err.to_string(),
- }
- .into());
- }
- builder.build().context("Failed to build include matcher")?
- };
- ignored_entries
- .into_iter()
- .filter(|(path, is_dir)| include_matcher.matched(path, *is_dir).is_ignore())
- .collect()
- } else {
- // No .worktreeinclude file — default to copying all ignored entries
- ignored_entries
- };
-
- // Filter out entries that contain other worktrees (prevents recursive copying when
- // worktrees are nested inside the source, e.g., worktree-path = ".worktrees/...")
let worktree_paths: Vec<PathBuf> = repo
.list_worktrees()?
.into_iter()
.map(|wt| wt.path)
.collect();
- let entries_to_copy: Vec<_> = entries_to_copy
- .into_iter()
- .filter(|(entry_path, _)| {
- // Exclude if any worktree (other than source) is inside or equal to this entry
- !worktree_paths
- .iter()
- .any(|wt_path| wt_path != &source_path && wt_path.starts_with(entry_path))
- })
- .collect();
+ let entries_to_copy =
+ list_and_filter_ignored_entries(&source_path, &source_context, &worktree_paths)?;
if entries_to_copy.is_empty() {
eprintln!("{}", info_message("No matching files to copy"));
@@ -848,6 +861,380 @@ fn copy_dir_recursive_fallback(src: &Path, dest: &Path, force: bool) -> anyhow::
Ok(())
}
+/// Move a file or directory, falling back to copy+delete on cross-device errors.
+fn move_entry(src: &Path, dest: &Path, is_dir: bool) -> anyhow::Result<()> {
+ // Ensure parent directory exists
+ if let Some(parent) = dest.parent() {
+ fs::create_dir_all(parent)
+ .context(format!("creating parent directory for {}", dest.display()))?;
+ }
+
+ match fs::rename(src, dest) {
+ Ok(()) => Ok(()),
+ Err(e) if e.kind() == ErrorKind::CrossesDevices => copy_and_remove(src, dest, is_dir),
+ Err(e) => Err(anyhow::Error::from(e).context(format!(
+ "moving {} to {}",
+ src.display(),
+ dest.display()
+ ))),
+ }
+}
+
+/// Copy then delete — fallback when `rename` fails with EXDEV (cross-device).
+fn copy_and_remove(src: &Path, dest: &Path, is_dir: bool) -> anyhow::Result<()> {
+ if is_dir {
+ copy_dir_recursive(src, dest, true)?;
+ fs::remove_dir_all(src).context(format!("removing source directory {}", src.display()))?;
+ } else {
+ reflink_copy::reflink_or_copy(src, dest).context(format!(
+ "copying {} to {}",
+ src.display(),
+ dest.display()
+ ))?;
+ fs::remove_file(src).context(format!("removing source file {}", src.display()))?;
+ }
+ Ok(())
+}
+
+const PROMOTE_STAGING_DIR: &str = "wt-promote-staging";
+
+/// Move gitignored files from both worktrees into a staging directory.
+///
+/// Called BEFORE the branch exchange because `git switch` silently overwrites
+/// ignored files that collide with tracked files on the target branch.
+///
+/// Returns the staging directory path and the count of entries staged.
+fn stage_ignored(
+ repo: &Repository,
+ path_a: &Path,
+ entries_a: &[(PathBuf, bool)],
+ path_b: &Path,
+ entries_b: &[(PathBuf, bool)],
+) -> anyhow::Result<(PathBuf, usize)> {
+ let staging_dir = repo.git_common_dir().join(PROMOTE_STAGING_DIR);
+ fs::create_dir_all(&staging_dir).context("creating promote staging directory")?;
+
+ let staging_a = staging_dir.join("a");
+ let staging_b = staging_dir.join("b");
+ let mut count = 0;
+
+ // Move A's entries → staging/a
+ for (src_entry, is_dir) in entries_a {
+ let relative = src_entry
+ .strip_prefix(path_a)
+ .context("entry not under worktree A")?;
+ let staging_entry = staging_a.join(relative);
+ if fs::symlink_metadata(src_entry).is_ok() {
+ move_entry(src_entry, &staging_entry, *is_dir)
+ .context(format!("staging {}", relative.display()))?;
+ count += 1;
+ }
+ }
+
+ // Move B's entries → staging/b
+ for (src_entry, is_dir) in entries_b {
+ let relative = src_entry
+ .strip_prefix(path_b)
+ .context("entry not under worktree B")?;
+ let staging_entry = staging_b.join(relative);
+ if fs::symlink_metadata(src_entry).is_ok() {
+ move_entry(src_entry, &staging_entry, *is_dir)
+ .context(format!("staging {}", relative.display()))?;
+ count += 1;
+ }
+ }
+
+ // Clean up empty staging directory (can happen if all entries vanished
+ // between listing and staging due to TOCTOU)
+ if count == 0 && staging_dir.exists() {
+ let _ = fs::remove_dir_all(&staging_dir);
+ }
+
+ Ok((staging_dir, count))
+}
+
+/// Distribute staged files to their new worktrees after a branch exchange.
+///
+/// B's original files (in staging/b) go to worktree A (which now has B's branch).
+/// A's original files (in staging/a) go to worktree B (which now has A's branch).
+fn distribute_staged(
+ staging_dir: &Path,
+ path_a: &Path,
+ entries_a: &[(PathBuf, bool)],
+ path_b: &Path,
+ entries_b: &[(PathBuf, bool)],
+) -> anyhow::Result<usize> {
+ let staging_a = staging_dir.join("a");
+ let staging_b = staging_dir.join("b");
+ let mut count = 0;
+
+ // Move B's staged entries → A (A now has B's branch)
+ for (src_entry, is_dir) in entries_b {
+ let relative = src_entry
+ .strip_prefix(path_b)
+ .context("entry not under worktree B")?;
+ let staging_entry = staging_b.join(relative);
+ let dest_entry = path_a.join(relative);
+ if fs::symlink_metadata(&staging_entry).is_ok() {
+ move_entry(&staging_entry, &dest_entry, *is_dir)
+ .context(format!("distributing {}", relative.display()))?;
+ count += 1;
+ }
+ }
+
+ // Move A's staged entries → B (B now has A's branch)
+ for (src_entry, is_dir) in entries_a {
+ let relative = src_entry
+ .strip_prefix(path_a)
+ .context("entry not under worktree A")?;
+ let staging_entry = staging_a.join(relative);
+ let dest_entry = path_b.join(relative);
+ if fs::symlink_metadata(&staging_entry).is_ok() {
+ move_entry(&staging_entry, &dest_entry, *is_dir)
+ .context(format!("distributing {}", relative.display()))?;
+ count += 1;
+ }
+ }
+
+ // Clean up staging directory (best-effort — files are already distributed)
+ let _ = fs::remove_dir_all(staging_dir);
+
+ Ok(count)
+}
+
+/// Result of a promote operation
+pub enum PromoteResult {
+ /// Branch was promoted successfully
+ Promoted,
+ /// Already in canonical state (requested branch is already in main)
+ AlreadyInMain(String),
+}
+
+/// Exchange branches between two worktrees.
+///
+/// Steps: detach target → detach main → switch main → switch target.
+/// Both worktrees must be clean (verified by caller). On failure, attempts
+/// best-effort rollback — but failure here is near-impossible given the
+/// preconditions (`ensure_clean` passed, branches exist, detach released locks).
+fn exchange_branches(
+ main_wt: &worktrunk::git::WorkingTree<'_>,
+ main_branch: &str,
+ target_wt: &worktrunk::git::WorkingTree<'_>,
+ target_branch: &str,
+) -> anyhow::Result<()> {
+ let steps: &[(&worktrunk::git::WorkingTree<'_>, &[&str], &str)] = &[
+ (target_wt, &["switch", "--detach"], "detach target"),
+ (main_wt, &["switch", "--detach"], "detach main"),
+ (main_wt, &["switch", target_branch], "switch main"),
+ (target_wt, &["switch", main_branch], "switch target"),
+ ];
+
+ for (wt, args, label) in steps {
+ if let Err(e) = wt.run_command(args) {
+ // Best-effort rollback: try to re-attach both branches.
+ let _ = main_wt.run_command(&["switch", main_branch]);
+ let _ = target_wt.run_command(&["switch", target_branch]);
+ return Err(e.context(format!("branch exchange failed at: {label}")));
+ }
+ }
+
+ Ok(())
+}
+
+/// Handle `wt step promote` command
+///
+/// Promotes a branch to the main worktree, exchanging it with whatever branch is currently there.
+///
+/// ## Interruption recovery
+///
+/// The swap uses a staging directory at `.git/wt-promote-staging/` and proceeds
+/// in three phases:
+///
+/// 1. **Stage**: move ignored files from both worktrees into staging (`a/`, `b/`)
+/// 2. **Exchange**: detach + `git switch` to swap branches
+/// 3. **Distribute**: move staged files to their new worktrees, then delete staging
+///
+/// A hard kill at any phase leaves files in staging, never deleted. The next run
+/// detects the leftover directory and bails with a recovery path. A kill during
+/// `git switch` may leave a worktree detached (fix: `git switch <branch>`).
+pub fn handle_promote(branch: Option<&str>) -> anyhow::Result<PromoteResult> {
+ use worktrunk::git::GitError;
+
+ let repo = Repository::current()?;
+ let worktrees = repo.list_worktrees()?;
+
+ if worktrees.is_empty() {
+ anyhow::bail!("No worktrees found");
+ }
+
+ // For normal repos, worktrees[0] is the main worktree
+ // For bare repos, there's no main worktree - we don't support promote there
+ if repo.is_bare() {
+ anyhow::bail!("wt step promote is not supported in bare repositories");
+ }
+
+ let main_wt = &worktrees[0];
+ let main_path = &main_wt.path;
+ let main_branch = main_wt
+ .branch
+ .clone()
+ .ok_or_else(|| GitError::DetachedHead {
+ action: Some("promote".into()),
+ })?;
+
+ // Resolve the branch to promote (default_branch computed lazily, only when needed)
+ let target_branch = match branch {
+ Some(b) => b.to_string(),
+ None => {
+ let current_wt = repo.current_worktree();
+ if !current_wt.is_linked()? {
+ // From main worktree with no args: restore default branch
+ repo.default_branch()
+ .ok_or_else(|| anyhow::anyhow!("Could not determine default branch"))?
+ } else {
+ // From other worktree with no args: promote current branch
+ current_wt.branch()?.ok_or_else(|| GitError::DetachedHead {
+ action: Some("promote".into()),
+ })?
+ }
+ }
+ };
+
+ // Check if target is already in main worktree
+ if target_branch == main_branch {
+ return Ok(PromoteResult::AlreadyInMain(target_branch));
+ }
+
+ // Find the worktree with the target branch
+ let target_wt = worktrees
+ .iter()
+ .skip(1) // Skip main worktree
+ .find(|wt| wt.branch.as_deref() == Some(&target_branch))
+ .ok_or_else(|| GitError::WorktreeNotFound {
+ branch: target_branch.clone(),
+ })?;
+
+ let target_path = &target_wt.path;
+
+ // Bail early if a leftover staging dir exists from a previous interrupted promote —
+ // it may contain the user's only copy of files from the failed swap.
+ // Check BEFORE ensure_clean so users see the recovery path first.
+ let staging_path = repo.git_common_dir().join(PROMOTE_STAGING_DIR);
+ if staging_path.exists() {
+ return Err(anyhow::anyhow!(
+ "Files may need manual recovery from: {}\n\
+ Remove it to retry: rm -rf \"{}\"",
+ staging_path.display(),
+ staging_path.display()
+ )
+ .context("Found leftover staging directory from an interrupted promote"));
+ }
+
+ // Ensure both worktrees are clean
+ let main_working_tree = repo.worktree_at(main_path);
+ let target_working_tree = repo.worktree_at(target_path);
+
+ main_working_tree.ensure_clean("promote", Some(&main_branch), false)?;
+ target_working_tree.ensure_clean("promote", Some(&target_branch), false)?;
+
+ // Check if we're restoring canonical state (promoting default branch back to main worktree)
+ // Only lookup default_branch if needed for messaging (already resolved if no-arg from main)
+ let default_branch = repo.default_branch();
+ let is_restoring = default_branch.as_ref() == Some(&target_branch);
+
+ if is_restoring {
+ // Restoring default branch to main worktree - no warning needed
+ eprintln!("{}", info_message("Restoring main worktree"));
+ } else {
+ // Creating mismatch - show warning and how to restore
+ eprintln!(
+ "{}",
+ warning_message("Promoting creates mismatched worktree state (shown as ⚑ in wt list)",)
+ );
+ // Only show restore hint if we know the default branch
+ if let Some(default) = &default_branch {
+ eprintln!(
+ "{}",
+ hint_message(cformat!(
+ "Run <bright-black>wt step promote {default}</> to restore canonical locations"
+ ))
+ );
+ }
+ }
+
+ // Discover gitignored entries BEFORE branch exchange — .gitignore rules belong
+ // to the current branch and will change after `git switch`.
+ let worktree_paths: Vec<PathBuf> = worktrees.iter().map(|wt| wt.path.clone()).collect();
+ let main_entries = list_and_filter_ignored_entries(main_path, &main_branch, &worktree_paths)?;
+ let target_entries =
+ list_and_filter_ignored_entries(target_path, &target_branch, &worktree_paths)?;
+
+ // Move gitignored files to staging BEFORE branch exchange.
+ // `git switch` silently overwrites ignored files that collide with tracked
+ // files on the target branch — staging them first prevents data loss.
+ let staged = if !main_entries.is_empty() || !target_entries.is_empty() {
+ let (dir, count) = stage_ignored(
+ &repo,
+ main_path,
+ &main_entries,
+ target_path,
+ &target_entries,
+ )
+ .context(format!(
+ "Failed to stage ignored files. Already-staged files may be recoverable from: {}",
+ staging_path.display()
+ ))?;
+ if count > 0 { Some((dir, count)) } else { None }
+ } else {
+ None
+ };
+
+ // Exchange branches (detach both, then switch to swapped branches).
+ // Failure is near-impossible (both worktrees verified clean, branches exist).
+ // If it somehow fails, stale staging detection recovers on next run.
+ exchange_branches(
+ &main_working_tree,
+ &main_branch,
+ &target_working_tree,
+ &target_branch,
+ )?;
+
+ // Distribute staged files to their new worktrees (after branch exchange)
+ let swapped = if let Some((ref staging_dir, _)) = staged {
+ distribute_staged(
+ staging_dir,
+ main_path,
+ &main_entries,
+ target_path,
+ &target_entries,
+ )
+ .context(format!(
+ "Failed to distribute staged files. Staged files may be recoverable from: {}",
+ staging_dir.display()
+ ))?
+ } else {
+ 0
+ };
+
+ // Print success messages only after everything succeeded
+ eprintln!(
+ "{}",
+ success_message(cformat!(
+ "Promoted: main worktree now has <bold>{target_branch}</>; {} now has <bold>{main_branch}</>",
+ worktrunk::path::format_path_for_display(target_path)
+ ))
+ );
+ if swapped > 0 {
+ let path_word = if swapped == 1 { "path" } else { "paths" };
+ eprintln!(
+ "{}",
+ success_message(format!("Swapped {swapped} gitignored {path_word}"))
+ );
+ }
+
+ Ok(PromoteResult::Promoted)
+}
+
/// Create a symlink, handling platform differences.
///
/// On Windows, distinguishes between file and directory symlinks by checking the
@@ -1009,4 +1396,70 @@ mod tests {
let dir = std::env::temp_dir();
assert!(remove_if_exists(&dir).is_err());
}
+
+ #[test]
+ fn test_move_entry_file() {
+ let tmp = tempfile::tempdir().unwrap();
+ let src = tmp.path().join("source.txt");
+ let dest = tmp.path().join("subdir/dest.txt");
+
+ fs::write(&src, "content").unwrap();
+ move_entry(&src, &dest, false).unwrap();
+
+ assert!(!src.exists());
+ assert_eq!(fs::read_to_string(&dest).unwrap(), "content");
+ }
+
+ #[test]
+ fn test_move_entry_directory() {
+ let tmp = tempfile::tempdir().unwrap();
+ let src = tmp.path().join("srcdir");
+ let dest = tmp.path().join("nested/destdir");
+
+ fs::create_dir_all(src.join("inner")).unwrap();
+ fs::write(src.join("inner/file.txt"), "nested").unwrap();
+ fs::write(src.join("root.txt"), "root").unwrap();
+
+ move_entry(&src, &dest, true).unwrap();
+
+ assert!(!src.exists());
+ assert_eq!(
+ fs::read_to_string(dest.join("inner/file.txt")).unwrap(),
+ "nested"
+ );
+ assert_eq!(fs::read_to_string(dest.join("root.txt")).unwrap(), "root");
+ }
+
+ #[test]
+ fn test_copy_and_remove_file() {
+ let tmp = tempfile::tempdir().unwrap();
+ let src = tmp.path().join("source.txt");
+ let dest = tmp.path().join("dest.txt");
+
+ fs::write(&src, "content").unwrap();
+ copy_and_remove(&src, &dest, false).unwrap();
+
+ assert!(!src.exists());
+ assert_eq!(fs::read_to_string(&dest).unwrap(), "content");
+ }
+
+ #[test]
+ fn test_copy_and_remove_directory() {
+ let tmp = tempfile::tempdir().unwrap();
+ let src = tmp.path().join("srcdir");
+ let dest = tmp.path().join("destdir");
+
+ fs::create_dir_all(src.join("sub")).unwrap();
+ fs::write(src.join("sub/file.txt"), "nested").unwrap();
+ fs::write(src.join("root.txt"), "root").unwrap();
+
+ copy_and_remove(&src, &dest, true).unwrap();
+
+ assert!(!src.exists());
+ assert_eq!(
+ fs::read_to_string(dest.join("sub/file.txt")).unwrap(),
+ "nested"
+ );
+ assert_eq!(fs::read_to_string(dest.join("root.txt")).unwrap(), "root");
+ }
}
diff --git a/src/main.rs b/src/main.rs
index 6f6fce157..c6ad33e05 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -49,11 +49,11 @@ use commands::{
MergeOptions, OperationMode, RebaseResult, SquashResult, SwitchOptions, add_approvals,
clear_approvals, handle_completions, handle_config_create, handle_config_show,
handle_config_update, handle_configure_shell, handle_hints_clear, handle_hints_get,
- handle_hook_show, handle_init, handle_list, handle_logs_get, handle_merge, handle_rebase,
- handle_remove, handle_remove_current, handle_show_theme, handle_squash, handle_state_clear,
- handle_state_clear_all, handle_state_get, handle_state_set, handle_state_show, handle_switch,
- handle_unconfigure_shell, resolve_worktree_arg, run_hook, step_commit, step_copy_ignored,
- step_diff, step_for_each, step_relocate,
+ handle_hook_show, handle_init, handle_list, handle_logs_get, handle_merge, handle_promote,
+ handle_rebase, handle_remove, handle_remove_current, handle_show_theme, handle_squash,
+ handle_state_clear, handle_state_clear_all, handle_state_get, handle_state_set,
+ handle_state_show, handle_switch, handle_unconfigure_shell, resolve_worktree_arg, run_hook,
+ step_commit, step_copy_ignored, step_diff, step_for_each, step_relocate,
};
use output::handle_remove_output;
@@ -550,6 +550,20 @@ fn main() {
force,
} => step_copy_ignored(from.as_deref(), to.as_deref(), dry_run, force),
StepCommand::ForEach { args } => step_for_each(args),
+ StepCommand::Promote { branch } => {
+ use commands::PromoteResult;
+ handle_promote(branch.as_deref()).map(|result| match result {
+ PromoteResult::Promoted => (),
+ PromoteResult::AlreadyInMain(branch) => {
+ eprintln!(
+ "{}",
+ info_message(cformat!(
+ "Branch <bold>{branch}</> is already in main worktree"
+ ))
+ );
+ }
+ })
+ }
StepCommand::Relocate {
branches,
dry_run,
diff --git a/tests/integration_tests/completion.rs b/tests/integration_tests/completion.rs
index af4062942..173482c49 100644
--- a/tests/integration_tests/completion.rs
+++ b/tests/integration_tests/completion.rs
@@ -593,11 +593,12 @@ fn test_complete_step_subcommands(repo: TestRepo) {
);
assert!(subcommands.contains(&"diff"), "Missing diff");
assert!(subcommands.contains(&"for-each"), "Missing for-each");
+ assert!(subcommands.contains(&"promote"), "Missing promote");
assert!(subcommands.contains(&"relocate"), "Missing relocate");
assert_eq!(
subcommands.len(),
- 8,
- "Should have exactly 8 step subcommands"
+ 9,
+ "Should have exactly 9 step subcommands"
);
}
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index b9e66ede5..70b5e6b56 100644
--- a/tests/integration_tests/help.rs
+++ b/tests/integration_tests/help.rs
@@ -59,6 +59,7 @@ fn snapshot_help(test_name: &str, args: &[&str]) {
#[case("help_merge_long", "merge --help")]
#[case("help_step_short", "step -h")]
#[case("help_step_long", "step --help")]
+#[case("help_step_promote", "step promote --help")]
// Config subcommands (long help only - these are less frequently accessed)
#[case("help_config_shell", "config shell --help")]
#[case("help_config_create", "config create --help")]
diff --git a/tests/integration_tests/mod.rs b/tests/integration_tests/mod.rs
index 277867d4d..c9454a0e0 100644
--- a/tests/integration_tests/mod.rs
+++ b/tests/integration_tests/mod.rs
@@ -56,6 +56,7 @@ pub mod spacing_edge_cases;
pub mod statusline;
pub mod step_copy_ignored;
pub mod step_diff;
+pub mod step_promote;
pub mod step_relocate;
pub mod switch;
pub mod switch_picker;
diff --git a/tests/integration_tests/step_promote.rs b/tests/integration_tests/step_promote.rs
new file mode 100644
index 000000000..e38361fc6
--- /dev/null
+++ b/tests/integration_tests/step_promote.rs
@@ -0,0 +1,940 @@
+//! Integration tests for `wt step promote`
+
+use crate::common::{TestRepo, make_snapshot_cmd, repo, setup_snapshot_settings, wt_command};
+use insta_cmd::assert_cmd_snapshot;
+use rstest::rstest;
+use std::fs;
+use std::process::Command;
+
+/// Helper to get the current branch in a directory
+fn get_branch(repo: &TestRepo, dir: &std::path::Path) -> String {
+ let output = repo
+ .git_command()
+ .args(["rev-parse", "--abbrev-ref", "HEAD"])
+ .current_dir(dir)
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "git rev-parse failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ String::from_utf8_lossy(&output.stdout).trim().to_string()
+}
+
+/// Test promoting from another worktree (no argument)
+#[rstest]
+fn test_promote_from_worktree(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // Run promote from the worktree (no argument needed)
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote"],
+ Some(&feature_path),
+ ));
+
+ // Verify branches were exchanged
+ assert_eq!(
+ get_branch(&repo, repo.root_path()),
+ "feature",
+ "main worktree should now have feature"
+ );
+ assert_eq!(
+ get_branch(&repo, &feature_path),
+ "main",
+ "other worktree should now have main"
+ );
+}
+
+/// Test promoting by specifying branch name
+#[rstest]
+fn test_promote_with_branch_argument(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // Run promote from main worktree, specifying the branch
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ Some(repo.root_path()),
+ ));
+
+ // Verify branches were exchanged
+ assert_eq!(
+ get_branch(&repo, repo.root_path()),
+ "feature",
+ "main worktree should now have feature"
+ );
+ assert_eq!(
+ get_branch(&repo, &feature_path),
+ "main",
+ "other worktree should now have main"
+ );
+}
+
+/// Test restoring canonical state
+#[rstest]
+fn test_promote_restore(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // First promote: feature to main worktree
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "first promote failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Verify first promote worked
+ assert_eq!(get_branch(&repo, repo.root_path()), "feature");
+
+ // Restore: promote main back (now 'main' is in the other worktree)
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "main"],
+ Some(repo.root_path()),
+ ));
+
+ // Verify canonical state restored
+ assert_eq!(
+ get_branch(&repo, repo.root_path()),
+ "main",
+ "main worktree should have main again"
+ );
+ assert_eq!(
+ get_branch(&repo, &feature_path),
+ "feature",
+ "other worktree should have feature again"
+ );
+}
+
+/// Test when branch is already in main worktree
+#[rstest]
+fn test_promote_already_in_main(repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ // 'main' is already in main worktree
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "main"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Test auto-restore with no argument from main worktree (after prior promote)
+#[rstest]
+fn test_promote_auto_restore(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // First promote: feature to main worktree (creates mismatch)
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "first promote failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Verify first promote worked
+ assert_eq!(get_branch(&repo, repo.root_path()), "feature");
+ assert_eq!(get_branch(&repo, &feature_path), "main");
+
+ // Auto-restore: no argument from main worktree restores default branch
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote"],
+ Some(repo.root_path()),
+ ));
+
+ // Verify canonical state restored
+ assert_eq!(
+ get_branch(&repo, repo.root_path()),
+ "main",
+ "main worktree should have main again"
+ );
+ assert_eq!(
+ get_branch(&repo, &feature_path),
+ "feature",
+ "other worktree should have feature again"
+ );
+}
+
+/// Test auto-restore when no argument from main worktree (already canonical)
+#[rstest]
+fn test_promote_no_arg_from_main(repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ // From main worktree with no arg: restores default branch (already there)
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Test error when branch has no worktree
+#[rstest]
+fn test_promote_branch_not_in_worktree(repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ // Create a branch but don't make a worktree for it
+ repo.run_git(&["branch", "orphan"]);
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "orphan"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Test error when main worktree is dirty
+#[rstest]
+fn test_promote_dirty_main(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let _feature_path = repo.add_worktree("feature");
+
+ // Make main worktree dirty
+ fs::write(repo.root_path().join("dirty.txt"), "uncommitted").unwrap();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Test error when target worktree is dirty
+#[rstest]
+fn test_promote_dirty_target(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // Make target worktree dirty
+ fs::write(feature_path.join("dirty.txt"), "uncommitted").unwrap();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Test that wt list shows mismatch indicator after promote
+#[rstest]
+fn test_promote_shows_mismatch_in_list(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let _feature_path = repo.add_worktree("feature");
+
+ // Promote
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "promote failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // List should show mismatch indicators
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "list",
+ &[],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Test error when run in a bare repository (no worktrees)
+#[test]
+fn test_promote_bare_repo_no_worktrees() {
+ let temp_dir = tempfile::tempdir().unwrap();
+ let bare_repo = temp_dir.path().join("bare.git");
+
+ // Create a bare repository
+ Command::new("git")
+ .args(["init", "--bare"])
+ .arg(&bare_repo)
+ .output()
+ .unwrap();
+
+ // Try to run promote in the bare repo - fails with "No worktrees found"
+ let output = wt_command()
+ .args(["step", "promote", "feature"])
+ .current_dir(&bare_repo)
+ .output()
+ .unwrap();
+
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(!output.status.success());
+ assert!(
+ stderr.contains("No worktrees found"),
+ "Expected no worktrees error, got: {stderr}"
+ );
+}
+
+/// Test error when run in a bare repository with worktrees
+#[test]
+fn test_promote_bare_repo_with_worktrees() {
+ let temp_dir = tempfile::tempdir().unwrap();
+ let bare_repo = temp_dir.path().join("bare.git");
+ let worktree_path = temp_dir.path().join("worktree");
+ let temp_clone = temp_dir.path().join("temp");
+
+ // Create a bare repository
+ Command::new("git")
+ .args(["init", "--bare", "--initial-branch=main"])
+ .arg(&bare_repo)
+ .output()
+ .unwrap();
+
+ // Create a commit via a temporary clone
+ Command::new("git")
+ .args([
+ "clone",
+ bare_repo.to_str().unwrap(),
+ temp_clone.to_str().unwrap(),
+ ])
+ .output()
+ .unwrap();
+
+ Command::new("git")
+ .args(["config", "user.email", "[email protected]"])
+ .current_dir(&temp_clone)
+ .output()
+ .unwrap();
+
+ Command::new("git")
+ .args(["config", "user.name", "Test"])
+ .current_dir(&temp_clone)
+ .output()
+ .unwrap();
+
+ Command::new("git")
+ .args(["commit", "--allow-empty", "-m", "init"])
+ .current_dir(&temp_clone)
+ .output()
+ .unwrap();
+
+ Command::new("git")
+ .args(["push", "origin", "main"])
+ .current_dir(&temp_clone)
+ .output()
+ .unwrap();
+
+ // Add a worktree to the bare repo
+ Command::new("git")
+ .args([
+ "--git-dir",
+ bare_repo.to_str().unwrap(),
+ "worktree",
+ "add",
+ worktree_path.to_str().unwrap(),
+ "main",
+ ])
+ .output()
+ .unwrap();
+
+ // Try to run promote in the bare repo - should fail with bare repo error
+ let output = wt_command()
+ .args(["step", "promote", "feature"])
+ .current_dir(&bare_repo)
+ .output()
+ .unwrap();
+
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(!output.status.success());
+ assert!(
+ stderr.contains("bare repositories"),
+ "Expected bare repo error, got: {stderr}"
+ );
+}
+
+/// Test error when main worktree has detached HEAD
+#[rstest]
+fn test_promote_detached_head_main(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let _feature_path = repo.add_worktree("feature");
+
+ // Detach HEAD in main worktree
+ let sha = repo
+ .git_command()
+ .args(["rev-parse", "HEAD"])
+ .current_dir(repo.root_path())
+ .output()
+ .unwrap();
+ let sha = String::from_utf8_lossy(&sha.stdout).trim().to_string();
+
+ repo.git_command()
+ .args(["checkout", "--detach", &sha])
+ .current_dir(repo.root_path())
+ .output()
+ .unwrap();
+
+ // Promote should fail due to detached HEAD
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Helper: commit a .gitignore in a worktree
+fn commit_gitignore(repo: &TestRepo, dir: &std::path::Path, content: &str) {
+ fs::write(dir.join(".gitignore"), content).unwrap();
+ repo.run_git_in(dir, &["add", ".gitignore"]);
+ repo.run_git_in(dir, &["commit", "-m", "add gitignore"]);
+}
+
+// ─── Swap tests ───────────────────────────────────────────────────────────
+
+/// Both worktrees have gitignored files — verify complete bidirectional swap
+#[rstest]
+fn test_promote_swap_bidirectional(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n*.log\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Main: build/main-artifact, app.log
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/main-artifact"), "main build").unwrap();
+ fs::write(repo.root_path().join("app.log"), "main log").unwrap();
+
+ // Feature: build/feature-artifact, debug.log
+ fs::create_dir_all(feature_path.join("build")).unwrap();
+ fs::write(feature_path.join("build/feature-artifact"), "feature build").unwrap();
+ fs::write(feature_path.join("debug.log"), "feature log").unwrap();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ Some(repo.root_path()),
+ ));
+
+ // Main worktree (now feature) should have feature's files
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/feature-artifact")).unwrap(),
+ "feature build"
+ );
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("debug.log")).unwrap(),
+ "feature log"
+ );
+ assert!(!repo.root_path().join("build/main-artifact").exists());
+ assert!(!repo.root_path().join("app.log").exists());
+
+ // Feature worktree (now main) should have main's files
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/main-artifact")).unwrap(),
+ "main build"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("app.log")).unwrap(),
+ "main log"
+ );
+ assert!(!feature_path.join("build/feature-artifact").exists());
+ assert!(!feature_path.join("debug.log").exists());
+}
+
+/// Only main worktree has gitignored files — they should move to the other worktree
+#[rstest]
+fn test_promote_swap_only_main_has_ignored(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n*.log\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Only main has ignored files
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/artifact"), "main artifact").unwrap();
+ fs::write(repo.root_path().join("app.log"), "main log").unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Main worktree should be clean (no ignored files)
+ assert!(!repo.root_path().join("build").exists());
+ assert!(!repo.root_path().join("app.log").exists());
+
+ // Feature worktree should have main's files
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/artifact")).unwrap(),
+ "main artifact"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("app.log")).unwrap(),
+ "main log"
+ );
+}
+
+/// Only feature worktree has gitignored files — they should move to the main worktree
+#[rstest]
+fn test_promote_swap_only_feature_has_ignored(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Only feature has ignored files
+ fs::create_dir_all(feature_path.join("build")).unwrap();
+ fs::write(feature_path.join("build/artifact"), "feature artifact").unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Main worktree should have feature's files
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/artifact")).unwrap(),
+ "feature artifact"
+ );
+
+ // Feature worktree should be clean
+ assert!(!feature_path.join("build").exists());
+}
+
+/// Neither worktree has gitignored files — promote should succeed without swap message
+#[rstest]
+fn test_promote_swap_no_ignored_files(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let _feature_path = repo.add_worktree("feature");
+
+ // No .gitignore, no ignored files — just promote
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ Some(repo.root_path()),
+ ));
+}
+
+/// Directories with nested structure are swapped correctly (deep nesting)
+#[rstest]
+fn test_promote_swap_nested_directories(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Main: deep nested structure
+ fs::create_dir_all(repo.root_path().join("build/debug/x86/obj")).unwrap();
+ fs::write(
+ repo.root_path().join("build/debug/x86/obj/main.o"),
+ "main object",
+ )
+ .unwrap();
+ fs::write(repo.root_path().join("build/debug/main.bin"), "main binary").unwrap();
+
+ // Feature: different nested structure
+ fs::create_dir_all(feature_path.join("build/release/arm64")).unwrap();
+ fs::write(
+ feature_path.join("build/release/arm64/feature.bin"),
+ "feature binary",
+ )
+ .unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Main worktree should have feature's structure
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/release/arm64/feature.bin")).unwrap(),
+ "feature binary"
+ );
+ assert!(!repo.root_path().join("build/debug").exists());
+
+ // Feature worktree should have main's structure
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/debug/x86/obj/main.o")).unwrap(),
+ "main object"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/debug/main.bin")).unwrap(),
+ "main binary"
+ );
+ assert!(!feature_path.join("build/release").exists());
+}
+
+/// Same-named ignored files with different content are swapped (not clobbered)
+#[rstest]
+fn test_promote_swap_same_filename_different_content(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Both have build/output.bin with different content
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/output.bin"), "main output").unwrap();
+
+ fs::create_dir_all(feature_path.join("build")).unwrap();
+ fs::write(feature_path.join("build/output.bin"), "feature output").unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Content should be swapped, not lost
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/output.bin")).unwrap(),
+ "feature output",
+ "main worktree should have feature's content"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/output.bin")).unwrap(),
+ "main output",
+ "feature worktree should have main's content"
+ );
+}
+
+/// Promote and restore round-trip preserves gitignored files
+#[rstest]
+fn test_promote_swap_roundtrip(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n*.log\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Create ignored files
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/artifact"), "main build").unwrap();
+ fs::write(repo.root_path().join("app.log"), "main log").unwrap();
+
+ fs::create_dir_all(feature_path.join("build")).unwrap();
+ fs::write(feature_path.join("build/artifact"), "feature build").unwrap();
+ fs::write(feature_path.join("debug.log"), "feature log").unwrap();
+
+ // Promote feature → main
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Restore: promote main back
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "main"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // After round-trip: everything should be back to original state
+ assert_eq!(get_branch(&repo, repo.root_path()), "main");
+ assert_eq!(get_branch(&repo, &feature_path), "feature");
+
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/artifact")).unwrap(),
+ "main build",
+ "main worktree should have its original build artifact back"
+ );
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("app.log")).unwrap(),
+ "main log"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/artifact")).unwrap(),
+ "feature build",
+ "feature worktree should have its original build artifact back"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("debug.log")).unwrap(),
+ "feature log"
+ );
+}
+
+/// .worktreeinclude limits which ignored files are swapped
+#[rstest]
+fn test_promote_swap_respects_worktreeinclude(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ // .worktreeinclude only includes build/ — .env and *.log should NOT be swapped
+ let gitignore = "build/\n*.log\n.env\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Commit .worktreeinclude on both branches (must be tracked for clean worktree)
+ fs::write(repo.root_path().join(".worktreeinclude"), "build/\n").unwrap();
+ repo.run_git(&["add", ".worktreeinclude"]);
+ repo.run_git(&["commit", "-m", "add worktreeinclude"]);
+
+ fs::write(feature_path.join(".worktreeinclude"), "build/\n").unwrap();
+ repo.run_git_in(&feature_path, &["add", ".worktreeinclude"]);
+ repo.run_git_in(&feature_path, &["commit", "-m", "add worktreeinclude"]);
+
+ // Main: build/ + .env + app.log
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/main-bin"), "main binary").unwrap();
+ fs::write(repo.root_path().join(".env"), "MAIN_SECRET=1").unwrap();
+ fs::write(repo.root_path().join("app.log"), "main log").unwrap();
+
+ // Feature: build/ + .env + debug.log
+ fs::create_dir_all(feature_path.join("build")).unwrap();
+ fs::write(feature_path.join("build/feature-bin"), "feature binary").unwrap();
+ fs::write(feature_path.join(".env"), "FEATURE_SECRET=1").unwrap();
+ fs::write(feature_path.join("debug.log"), "feature log").unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // build/ should be swapped (matches .worktreeinclude)
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/feature-bin")).unwrap(),
+ "feature binary"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/main-bin")).unwrap(),
+ "main binary"
+ );
+
+ // .env and *.log should NOT be swapped (excluded by .worktreeinclude)
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join(".env")).unwrap(),
+ "MAIN_SECRET=1",
+ ".env should stay in place"
+ );
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("app.log")).unwrap(),
+ "main log",
+ "app.log should stay in place"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join(".env")).unwrap(),
+ "FEATURE_SECRET=1",
+ ".env should stay in place"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("debug.log")).unwrap(),
+ "feature log",
+ "debug.log should stay in place"
+ );
+}
+
+/// No stale staging directory left after successful promote
+#[rstest]
+fn test_promote_swap_no_staging_leftover(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/artifact"), "data").unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // The staging directory should be cleaned up
+ let git_dir = repo.root_path().join(".git");
+ assert!(
+ !git_dir.join("wt-promote-staging").exists(),
+ "staging directory should be cleaned up after promote"
+ );
+}
+
+/// Tracked files are not affected by the swap
+#[rstest]
+fn test_promote_swap_does_not_touch_tracked_files(mut repo: TestRepo) {
+ let feature_path = repo.add_worktree("feature");
+
+ let gitignore = "build/\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+
+ // Create a tracked file on main (committed, not ignored)
+ fs::write(repo.root_path().join("src.txt"), "main source").unwrap();
+ repo.run_git(&["add", "src.txt"]);
+ repo.run_git(&["commit", "-m", "add source"]);
+
+ // Create a tracked file on feature
+ fs::write(feature_path.join("feat.txt"), "feature source").unwrap();
+ repo.run_git_in(&feature_path, &["add", "feat.txt"]);
+ repo.run_git_in(&feature_path, &["commit", "-m", "add feat source"]);
+
+ // Create ignored files
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/main.o"), "main obj").unwrap();
+ fs::create_dir_all(feature_path.join("build")).unwrap();
+ fs::write(feature_path.join("build/feat.o"), "feat obj").unwrap();
+
+ let output = repo
+ .wt_command()
+ .args(["step", "promote", "feature"])
+ .output()
+ .unwrap();
+ assert!(
+ output.status.success(),
+ "{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ // Tracked files should follow their branches (via git switch, not our swap)
+ // Main worktree (now on feature) should have feat.txt from git switch
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("feat.txt")).unwrap(),
+ "feature source"
+ );
+ // Feature worktree (now on main) should have src.txt from git switch
+ assert_eq!(
+ fs::read_to_string(feature_path.join("src.txt")).unwrap(),
+ "main source"
+ );
+
+ // Ignored files should be swapped by our code
+ assert_eq!(
+ fs::read_to_string(repo.root_path().join("build/feat.o")).unwrap(),
+ "feat obj"
+ );
+ assert_eq!(
+ fs::read_to_string(feature_path.join("build/main.o")).unwrap(),
+ "main obj"
+ );
+}
+
+/// Test that promote bails with guidance when stale staging directory exists
+#[rstest]
+fn test_promote_stale_staging_blocks_with_guidance(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // Need gitignored files so stage_ignored is actually called
+ let gitignore = "build/\n";
+ commit_gitignore(&repo, repo.root_path(), gitignore);
+ commit_gitignore(&repo, &feature_path, gitignore);
+ fs::create_dir_all(repo.root_path().join("build")).unwrap();
+ fs::write(repo.root_path().join("build/artifact"), "main build").unwrap();
+
+ // Create a fake leftover staging directory (as if previous promote was interrupted)
+ let git_dir = repo.root_path().join(".git");
+ let staging_dir = git_dir.join("wt-promote-staging");
+ fs::create_dir_all(staging_dir.join("a")).unwrap();
+ fs::write(staging_dir.join("a/leftover"), "leftover data").unwrap();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote", "feature"],
+ None
+ ));
+
+ // Staging dir should still exist (not destroyed)
+ assert!(staging_dir.exists(), "staging dir should be preserved");
+ assert_eq!(
+ fs::read_to_string(staging_dir.join("a/leftover")).unwrap(),
+ "leftover data"
+ );
+}
+
+/// Test error when linked worktree has detached HEAD (no-arg promote)
+#[rstest]
+fn test_promote_detached_head_linked(mut repo: TestRepo) {
+ let _settings_guard = setup_snapshot_settings(&repo).bind_to_scope();
+ let feature_path = repo.add_worktree("feature");
+
+ // Detach HEAD in the linked worktree
+ let sha = repo
+ .git_command()
+ .args(["rev-parse", "HEAD"])
+ .current_dir(&feature_path)
+ .output()
+ .unwrap();
+ let sha = String::from_utf8_lossy(&sha.stdout).trim().to_string();
+
+ repo.git_command()
+ .args(["checkout", "--detach", &sha])
+ .current_dir(&feature_path)
+ .output()
+ .unwrap();
+
+ // No-arg promote from linked worktree should fail due to detached HEAD
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["promote"],
+ Some(&feature_path),
+ ));
+}
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 a33789c28..7d3ec2169 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -44,6 +44,7 @@ Usage: wt step [OPTIONS] <COMMAND>
diff Show all changes since branching
copy-ignored Copy gitignored files to another worktree
for-each [experimental] Run command in each worktree
+ promote [experimental] Put a branch into the main worktree
relocate [experimental] Move worktrees to expected paths
Options:
@@ -82,6 +83,7 @@ Manual merge workflow with review between steps:
- diff — Show all changes since branching (committed, staged, unstaged, untracked)
- copy-ignored — Copy gitignored files between worktrees
- for-each — [experimental] Run a command in every worktree
+- promote — [experimental] Put a branch into the main worktree
- relocate — [experimental] Move worktrees to expected paths
See also
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap b/tests/snapshots/integration__integration_tests__help__help_step_promote.snap
new file mode 100644
index 000000000..aa09aaa2f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_promote.snap
@@ -0,0 +1,90 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ LANG: C
+ LC_ALL: C
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_APPROVALS_PATH: /nonexistent/test/approvals.toml
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
+ 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"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step promote - [experimental] Put a branch into the main worktree
+
+The displaced branch moves to the promoted branch's worktree.
+
+Usage: wt step promote [OPTIONS] [BRANCH]
+
+Arguments:
+ [BRANCH]
+ Branch to promote to main worktree
+
+ Defaults to current branch, or default branch from main worktree.
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose...
+ Verbose output (-v: hooks, templates; -vv: debug report)
+
+Experimental. Use promote for temporary testing when the main worktree has special significance (Docker Compose, IDE configs, heavy build artifacts anchored to project root), and hooks & tools aren't yet set up to run on arbitrary worktrees. The idiomatic Worktrunk workflow does not use promote; instead each worktree has a full environment. promote is the only Worktrunk command which changes a branch in an existing worktree.
+
+Example
+
+ # from ~/project (main worktree)
+ $ wt step promote feature
+
+Before:
+
+  Branch Path
+ @ main ~/project
+ + feature ~/project.feature
+
+After:
+
+  Branch Path
+ @ feature ~/project
+ + main ~/project.feature
+
+To restore: wt step promote main from anywhere, or just wt step promote from the main worktree.
+
+Without an argument, promotes the current branch — or restores the default branch if run from the main worktree.
+
+Requirements
+
+- Both worktrees must be clean
+- The branch must have an existing worktree
+
+Gitignored files
+
+Gitignored files are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. See copy-ignored for filtering with .worktreeinclude.
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index c35dc6ddb..d6c417cef 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -41,6 +41,7 @@ Usage: wt step [OPTIONS] <COMMAND>
diff Show all changes since branching
copy-ignored Copy gitignored files to another worktree
for-each [experimental] Run command in each worktree
+ promote [experimental] Put a branch into the main worktree
relocate [experimental] Move worktrees to expected paths
Options:
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_already_in_main.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_already_in_main.snap
new file mode 100644
index 000000000..2296b3f7e
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_already_in_main.snap
@@ -0,0 +1,39 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - main
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Branch main is already in main worktree
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_auto_restore.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_auto_restore.snap
new file mode 100644
index 000000000..1c63e12eb
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_auto_restore.snap
@@ -0,0 +1,39 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Restoring main worktree
+✓ Promoted: main worktree now has main; _REPO_.feature now has feature
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_branch_not_in_worktree.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_branch_not_in_worktree.snap
new file mode 100644
index 000000000..323c99ebd
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_branch_not_in_worktree.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - orphan
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Branch orphan has no worktree
+↳ To create a worktree, run wt switch orphan
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_detached_head_linked.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_detached_head_linked.snap
new file mode 100644
index 000000000..0332d8c1c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_detached_head_linked.snap
@@ -0,0 +1,39 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Cannot promote: not on a branch (detached HEAD)
+↳ To switch to a branch, run git switch <branch>
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_detached_head_main.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_detached_head_main.snap
new file mode 100644
index 000000000..53ec66dec
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_detached_head_main.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Cannot promote: not on a branch (detached HEAD)
+↳ To switch to a branch, run git switch <branch>
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_dirty_main.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_dirty_main.snap
new file mode 100644
index 000000000..5d97cc8fb
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_dirty_main.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Cannot promote: main has uncommitted changes
+↳ Commit or stash changes first
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_dirty_target.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_dirty_target.snap
new file mode 100644
index 000000000..0cdffdf44
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_dirty_target.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Cannot promote: feature has uncommitted changes
+↳ Commit or stash changes first
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_from_worktree.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_from_worktree.snap
new file mode 100644
index 000000000..384c01f42
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_from_worktree.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+▲ Promoting creates mismatched worktree state (shown as ⚑ in wt list)
+↳ Run wt step promote main to restore canonical locations
+✓ Promoted: main worktree now has feature; _REPO_.feature now has main
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_no_arg_from_main.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_no_arg_from_main.snap
new file mode 100644
index 000000000..70565cff4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_no_arg_from_main.snap
@@ -0,0 +1,38 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Branch main is already in main worktree
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_restore.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_restore.snap
new file mode 100644
index 000000000..019217886
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_restore.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - main
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+○ Restoring main worktree
+✓ Promoted: main worktree now has main; _REPO_.feature now has feature
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_shows_mismatch_in_list.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_shows_mismatch_in_list.snap
new file mode 100644
index 000000000..998e6680f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_shows_mismatch_in_list.snap
@@ -0,0 +1,50 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - list
+ 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]"
+ 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: true
+exit_code: 0
+----- stdout -----
+ Branch Status HEAD± main↕ Remote⇅ Path Commit Age Message
+@ feature ⚑^ . 05a4a45d 16h Initial commit
++ main ⚑_| | ../repo.feature 05a4a45d 16h Initial commit
++ feature-a ↑ ↑1 ../repo.feature-a 1b87d473 16h Add feature-a file
++ feature-b ↑ ↑1 ../repo.feature-b f62940fc 16h Add feature-b file
++ feature-c ↑ ↑1 ../repo.feature-c 345c7c93 16h Add feature-c file
+
+○ Showing 5 worktrees, 3 ahead
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_stale_staging_blocks_with_guidance.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_stale_staging_blocks_with_guidance.snap
new file mode 100644
index 000000000..f03f182aa
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_stale_staging_blocks_with_guidance.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ 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 -----
+✗ Found leftover staging directory from an interrupted promote
+  Files may need manual recovery from: _REPO_/.git/wt-promote-staging
+  Remove it to retry: rm -rf "_REPO_/.git/wt-promote-staging"
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_swap_bidirectional.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_swap_bidirectional.snap
new file mode 100644
index 000000000..537fc9ea7
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_swap_bidirectional.snap
@@ -0,0 +1,48 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ 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: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+▲ Promoting creates mismatched worktree state (shown as ⚑ in wt list)
+↳ Run wt step promote main to restore canonical locations
+✓ Promoted: main worktree now has feature; _REPO_.feature now has main
+✓ Swapped 4 gitignored paths
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_swap_no_ignored_files.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_swap_no_ignored_files.snap
new file mode 100644
index 000000000..cd2a32ba1
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_swap_no_ignored_files.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ 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: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+▲ Promoting creates mismatched worktree state (shown as ⚑ in wt list)
+↳ Run wt step promote main to restore canonical locations
+✓ Promoted: main worktree now has feature; _REPO_.feature now has main
diff --git a/tests/snapshots/integration__integration_tests__step_promote__promote_with_branch_argument.snap b/tests/snapshots/integration__integration_tests__step_promote__promote_with_branch_argument.snap
new file mode 100644
index 000000000..dc290f124
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_promote__promote_with_branch_argument.snap
@@ -0,0 +1,41 @@
+---
+source: tests/integration_tests/step_promote.rs
+info:
+ program: wt
+ args:
+ - step
+ - promote
+ - feature
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+▲ Promoting creates mismatched worktree state (shown as ⚑ in wt list)
+↳ Run wt step promote main to restore canonical locations
+✓ Promoted: main worktree now has feature; _REPO_.feature now has main