Skip to content

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

docs(step): add promote subdoc, improve swap description (#1505)

Maximilian Roos1cfa5f6806d5
diff --git a/docs/content/step.md b/docs/content/step.md
index c33f0e8e9..acb981b93 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -37,7 +37,7 @@ wt step push
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`for-each`](#wt-step-for-each) — [experimental] Run a command in every worktree
-- `promote` — [experimental] Put a branch into the main worktree
+- [`promote`](#wt-step-promote) — [experimental] Swap a branch into the main worktree
- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
- [`<alias>`](#aliases) — [experimental] Run a configured command alias
@@ -65,7 +65,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>promote</span></b> [experimental] Swap a branch into the main worktree
<b><span class=c>prune</span></b> [experimental] Remove worktrees merged into the default branch
<b><span class=c>relocate</span></b> [experimental] Move worktrees to expected paths
@@ -519,6 +519,80 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+## wt step promote
+
+[experimental] Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
+
+**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
+
+```bash
+# 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 (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.
+
+The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If `.git/` is on a different filesystem, it falls back to reflink copy.
+
+### Command reference
+
+{% terminal() %}
+wt step promote - [experimental] Swap a branch into the main worktree
+
+Exchanges branches and gitignored files between two worktrees.
+
+Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCH]</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[BRANCH]</span>
+ Branch to promote to main worktree
+
+ Defaults to current branch, or default branch from main worktree.
+
+<b><span class=g>Options:</span></b>
+ <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>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: hooks, templates; -vv: debug report)
+{% end %}
+
## wt step prune
[experimental] Remove worktrees merged into the default branch.
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 4d50c2332..09030e261 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -28,7 +28,7 @@ wt step push
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`for-each`](#wt-step-for-each) — [experimental] Run a command in every worktree
-- `promote` — [experimental] Put a branch into the main worktree
+- [`promote`](#wt-step-promote) — [experimental] Swap a branch into the main worktree
- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
- [`<alias>`](#aliases) — [experimental] Run a configured command alias
@@ -50,7 +50,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>promote</span></b> [experimental] Swap a branch into the main worktree
<b><span class=c>prune</span></b> [experimental] Remove worktrees merged into the default branch
<b><span class=c>relocate</span></b> [experimental] Move worktrees to expected paths
@@ -493,6 +493,78 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Verbose output (-v: hooks, templates; -vv: debug report)
+## wt step promote
+
+[experimental] Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.
+
+**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
+
+```bash
+# 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 (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.
+
+The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If `.git/` is on a different filesystem, it falls back to reflink copy.
+
+### Command reference
+
+wt step promote - [experimental] Swap a branch into the main worktree
+
+Exchanges branches and gitignored files between two worktrees.
+
+Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCH]</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[BRANCH]</span>
+ Branch to promote to main worktree
+
+ Defaults to current branch, or default branch from main worktree.
+
+<b><span class=g>Options:</span></b>
+ <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>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: hooks, templates; -vv: debug report)
+
## wt step prune
[experimental] Remove worktrees merged into the default branch.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e3036f05a..bd471ec13 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1050,7 +1050,7 @@ wt step push
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`for-each`](#wt-step-for-each) — [experimental] Run a command in every worktree
-- `promote` — [experimental] Put a branch into the main worktree
+- [`promote`](#wt-step-promote) — [experimental] Swap a branch into the main worktree
- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
- [`<alias>`](#aliases) — [experimental] Run a configured command alias
@@ -1065,6 +1065,7 @@ wt step push
<!-- subdoc: diff -->
<!-- subdoc: copy-ignored -->
<!-- subdoc: for-each -->
+<!-- subdoc: promote -->
<!-- subdoc: prune -->
<!-- subdoc: relocate -->
## Aliases
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 12a41cf7b..ace4c5900 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -373,9 +373,9 @@ Note: This command is experimental and may change in future versions.
args: Vec<String>,
},
- /// \[experimental\] Put a branch into the main worktree
+ /// \[experimental\] Swap a branch into the main worktree
///
- /// The displaced branch moves to the promoted branch's worktree.
+ /// Exchanges branches and gitignored files between two worktrees.
#[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.
@@ -413,7 +413,9 @@ Without an argument, promotes the current branch — or restores the default bra
## 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`.
+Gitignored files (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.
+
+The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If `.git/` is on a different filesystem, it falls back to reflink copy.
"#
)]
Promote {
diff --git a/src/commands/step_commands.rs b/src/commands/step_commands.rs
index 65469ab79..13fcc887f 100644
--- a/src/commands/step_commands.rs
+++ b/src/commands/step_commands.rs
@@ -9,7 +9,7 @@
//!
//! Standalone:
//! - `step_copy_ignored` - Copy gitignored files matching .worktreeinclude
-//! - `handle_promote` - Put a branch into the main worktree
+//! - `handle_promote` - Swap a branch into the main worktree
//! - `step_prune` - Remove worktrees merged into the default branch
use std::fs;
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 780e19f78..9e4cb53c3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -45,7 +45,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
+ promote [experimental] Swap a branch into the main worktree
prune [experimental] Remove worktrees merged into the default branch
relocate [experimental] Move worktrees to expected paths
@@ -85,7 +85,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
+- promote — [experimental] Swap a branch into the main worktree
- prune — Remove worktrees and branches merged into the default branch
- relocate — [experimental] Move worktrees to expected paths
- <alias> — [experimental] Run a configured command alias
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 b8ad717f2..603a80528 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_promote.snap
@@ -32,9 +32,9 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt step promote - [experimental] Put a branch into the main worktree
+wt step promote - [experimental] Swap a branch into the main worktree
-The displaced branch moves to the promoted branch's worktree.
+Exchanges branches and gitignored files between two worktrees.
Usage: wt step promote [OPTIONS] [BRANCH]
@@ -88,4 +88,6 @@ Without an argument, promotes the current branch — or restores the default bra
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.
+Gitignored files (build artifacts, node_modules/, .env) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as copy-ignored and can be filtered with .worktreeinclude.
+
+The swap uses rename() for each entry — fast regardless of entry size, since only filesystem metadata changes. If .git/ is on a different filesystem, it falls back to reflink copy.
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 7cfa3bbb9..93910c91c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -11,6 +11,7 @@ info:
GIT_EDITOR: ""
LANG: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -42,7 +43,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
+ promote [experimental] Swap a branch into the main worktree
prune [experimental] Remove worktrees merged into the default branch
relocate [experimental] Move worktrees to expected paths