Add experimental wt step promote command

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>

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>

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

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.

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,