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.mdindex 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]</spaVerbose 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 '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></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.mdindex 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 '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></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.rsindex 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 -->## Aliasesdiff --git a/src/cli/step.rs b/src/cli/step.rsindex 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.rsindex 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 branchuse 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.snapindex 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: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[36mdiff[0m Show all changes since branching[1m[36mcopy-ignored[0m Copy gitignored files to another worktree[1m[36mfor-each[0m [experimental] Run command in each worktree- [1m[36mpromote[0m [experimental] Put a branch into the main worktree+ [1m[36mpromote[0m [experimental] Swap a branch into the main worktree[1m[36mprune[0m [experimental] Remove worktrees merged into the default branch[1m[36mrelocate[0m [experimental] Move worktrees to expected paths@@ -85,7 +85,7 @@ Manual merge workflow with review between steps:- [2mdiff[0m — Show all changes since branching (committed, staged, unstaged, untracked)- [2mcopy-ignored[0m — Copy gitignored files between worktrees- [2mfor-each[0m — [experimental] Run a command in every worktree-- [2mpromote[0m — [experimental] Put a branch into the main worktree+- [2mpromote[0m — [experimental] Swap a branch into the main worktree- [2mprune[0m — Remove worktrees and branches merged into the default branch- [2mrelocate[0m — [experimental] Move worktrees to expected paths- [2m<alias>[0m — [experimental] Run a configured command aliasdiff --git a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap b/tests/snapshots/integration__integration_tests__help__help_step_promote.snapindex 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[0m+wt step promote - [experimental] Swap a branch into the main worktree[0m-The displaced branch moves to the promoted branch's worktree.[0m+Exchanges branches and gitignored files between two worktrees.[0mUsage: [1m[36mwt step promote[0m [36m[OPTIONS][0m [36m[BRANCH][0m@@ -88,4 +88,6 @@ Without an argument, promotes the current branch — or restores the default bra[1m[32mGitignored files[0m-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 [2m.worktreeinclude[0m.+Gitignored files (build artifacts, [2mnode_modules/[0m, [2m.env[0m) 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 [2mcopy-ignored[0m and can be filtered with [2m.worktreeinclude[0m.++The swap uses [2mrename()[0m for each entry — fast regardless of entry size, since only filesystem metadata changes. If [2m.git/[0m 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.snapindex 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: CLC_ALL: C+ NO_COLOR: ""PSModulePath: ""RUST_LOG: warnSHELL: ""@@ -42,7 +43,7 @@ Usage: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[36mdiff[0m Show all changes since branching[1m[36mcopy-ignored[0m Copy gitignored files to another worktree[1m[36mfor-each[0m [experimental] Run command in each worktree- [1m[36mpromote[0m [experimental] Put a branch into the main worktree+ [1m[36mpromote[0m [experimental] Swap a branch into the main worktree[1m[36mprune[0m [experimental] Remove worktrees merged into the default branch[1m[36mrelocate[0m [experimental] Move worktrees to expected paths