Skip to content

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

docs(step): render `wt step rebase` & `wt step push` on the docs site (#3578)

Maximilian Roosb17a1364f132
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 3e48bc1ad..a7b950eb1 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -304,7 +304,7 @@ This expands during `--help-page` generation to:
- The subcommand's help reference is formatted as a nested `### Command reference`
**Use cases:**
-- `wt config create` — Shows the actual config file templates (via `include_str!`)
+- `wt list statusline` — Surfaces output formats that would otherwise be terminal-only
- `wt config state marker` — Shows per-key examples not in the parent
All AUTO-GENERATED markers use a consistent format with START and END tags:
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 8de43cca0..b2fd99104 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -67,10 +67,10 @@ Preserve the exact clean commit graph and tip:
`wt merge` runs these steps:
1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. Skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.
-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
-3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
+3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](@/step.md#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](@/step.md#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
diff --git a/docs/content/step.md b/docs/content/step.md
index e7629361d..4af08d1cf 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -29,8 +29,8 @@ Manual merge workflow with review between steps:
- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](@/llm-commits.md)
- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
-- `rebase` — Rebase onto target branch
-- `push` — Fast-forward target to current branch
+- [`rebase`](#wt-step-rebase) — Rebase onto target branch
+- [`push`](#wt-step-push) — Fast-forward target to current branch
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`eval`](#wt-step-eval) — <span class="badge-experimental"></span> Evaluate a template expression
@@ -283,6 +283,147 @@ Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span>
Skip approval prompts
{% end %}
+## wt step rebase
+
+Rebase onto target.
+
+A rebase puts the branch's commits on top of the target, which is what [`wt step push`](#wt-step-push) needs — a push fast-forwards only if the target is an ancestor of the branch. `wt merge` runs this step as part of its pipeline; on its own it brings a branch up to date with a target that has moved, without merging into it.
+
+The target is any commit: a branch, a tag, a SHA.
+
+### Examples
+
+{{ terminal(cmd="wt step rebase # Rebase onto default branch|||wt step rebase develop # Rebase onto develop|||wt step rebase v1.2.0 # Rebase onto a tag") }}
+
+### Outcomes
+
+The first matching row wins:
+
+| Branch and target | Result |
+|-------------------|--------|
+| The target is already an ancestor of the branch, with no merge commit in between | Nothing runs — `Already up to date` |
+| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` |
+| Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |
+
+A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.
+
+When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](@/merge.md) covers why.
+
+### Conflicts
+
+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.
+
+### Command reference
+
+{% terminal() %}
+wt step rebase - Rebase onto target
+
+Usage: <b><span class=c>wt step rebase</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
+ Target branch, tag, or commit
+
+ Defaults to default branch.
+
+<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>Automation:</span></b>
+ <b><span class=c>--format</span></b><span class=c> &lt;FORMAT&gt;</span>
+ Output format
+
+ JSON prints structured result to stdout after the rebase completes.
+
+ [default: text]
+ [possible values: text, json]
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>--config-set</span></b><span class=c> &lt;toml&gt;</span>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+ logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+ apply the same level everywhere — including shell completion, which no flag can reach
+
+ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>
+ Skip approval prompts
+{% end %}
+
+## wt step push
+
+Fast-forward target to current branch.
+
+Despite the name, no commits leave the repository. The target branch's ref moves forward locally, and a worktree holding that branch is updated along with it. Publishing is a separate `git push` to the remote afterward.
+
+The target is a branch, and must already be an ancestor of the current branch. One that has moved ahead is refused, and there is no force variant — [`wt step rebase`](#wt-step-rebase) puts the branch back on top of it first.
+
+### Examples
+
+{{ terminal(cmd="wt step push # Fast-forward main to current branch|||wt step push develop # Fast-forward develop instead|||wt step push --no-ff # Merge commit instead of a fast-forward") }}
+
+### Target worktree
+
+When the target branch has a worktree of its own, that worktree's files move to the new commits too. A fast-forward does both at once, pushing into this repository with `receive.denyCurrentBranch=updateInstead`; `--no-ff` moves the ref first and syncs the worktree after, warning rather than failing if that sync doesn't apply. Uncommitted changes in that worktree are stashed for the duration and restored afterward; one touching a file the push also changes is refused instead, naming the file.
+
+A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.
+
+### Command reference
+
+{% terminal() %}
+wt step push - Fast-forward target to current branch
+
+Usage: <b><span class=c>wt step push</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
+ Target branch
+
+ Defaults to default branch.
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--no-ff</span></b>
+ Create a merge commit (no fast-forward)
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Automation:</span></b>
+ <b><span class=c>--format</span></b><span class=c> &lt;FORMAT&gt;</span>
+ Output format
+
+ JSON prints structured result to stdout after the push completes.
+
+ [default: text]
+ [possible values: text, json]
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>--config-set</span></b><span class=c> &lt;toml&gt;</span>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+ logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+ apply the same level everywhere — including shell completion, which no flag can reach
+
+ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>
+ Skip approval prompts
+{% end %}
+
## wt step diff
Show all changes since branching. Includes committed, staged, unstaged, and untracked files.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/merge.md b/plugins/worktrunk/skills/worktrunk/reference/merge.md
index cba3b8754..7781639f4 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/merge.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/merge.md
@@ -64,10 +64,10 @@ $ wt merge --no-commit --no-rebase
`wt merge` runs these steps:
1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. Skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.
-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
-3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
+3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](https://worktrunk.dev/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](https://worktrunk.dev/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.md
index 82fa91d43..631953640 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/step.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md
@@ -26,8 +26,8 @@ $ wt step push
- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](https://worktrunk.dev/llm-commits/)
- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](https://worktrunk.dev/llm-commits/)
-- `rebase` — Rebase onto target branch
-- `push` — Fast-forward target to current branch
+- [`rebase`](#wt-step-rebase) — Rebase onto target branch
+- [`push`](#wt-step-push) — Fast-forward target to current branch
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`eval`](#wt-step-eval) — [experimental] Evaluate a template expression
@@ -282,6 +282,155 @@ Global Options:
Skip approval prompts
```
+## wt step rebase
+
+Rebase onto target.
+
+A rebase puts the branch's commits on top of the target, which is what [`wt step push`](#wt-step-push) needs — a push fast-forwards only if the target is an ancestor of the branch. `wt merge` runs this step as part of its pipeline; on its own it brings a branch up to date with a target that has moved, without merging into it.
+
+The target is any commit: a branch, a tag, a SHA.
+
+### Examples
+
+```bash
+$ wt step rebase # Rebase onto default branch
+$ wt step rebase develop # Rebase onto develop
+$ wt step rebase v1.2.0 # Rebase onto a tag
+```
+
+### Outcomes
+
+The first matching row wins:
+
+| Branch and target | Result |
+|-------------------|--------|
+| The target is already an ancestor of the branch, with no merge commit in between | Nothing runs — `Already up to date` |
+| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` |
+| Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |
+
+A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.
+
+When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](https://worktrunk.dev/merge/) covers why.
+
+### Conflicts
+
+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.
+
+### Command reference
+
+```
+wt step rebase - Rebase onto target
+
+Usage: wt step rebase [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch, tag, or commit
+
+ Defaults to default branch.
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Automation:
+ --format <FORMAT>
+ Output format
+
+ JSON prints structured result to stdout after the rebase completes.
+
+ [default: text]
+ [possible values: text, json]
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ --config-set <toml>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ -v, --verbose...
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+ logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+ apply the same level everywhere — including shell completion, which no flag can reach
+
+ -y, --yes
+ Skip approval prompts
+```
+
+## wt step push
+
+Fast-forward target to current branch.
+
+Despite the name, no commits leave the repository. The target branch's ref moves forward locally, and a worktree holding that branch is updated along with it. Publishing is a separate `git push` to the remote afterward.
+
+The target is a branch, and must already be an ancestor of the current branch. One that has moved ahead is refused, and there is no force variant — [`wt step rebase`](#wt-step-rebase) puts the branch back on top of it first.
+
+### Examples
+
+```bash
+$ wt step push # Fast-forward main to current branch
+$ wt step push develop # Fast-forward develop instead
+$ wt step push --no-ff # Merge commit instead of a fast-forward
+```
+
+### Target worktree
+
+When the target branch has a worktree of its own, that worktree's files move to the new commits too. A fast-forward does both at once, pushing into this repository with `receive.denyCurrentBranch=updateInstead`; `--no-ff` moves the ref first and syncs the worktree after, warning rather than failing if that sync doesn't apply. Uncommitted changes in that worktree are stashed for the duration and restored afterward; one touching a file the push also changes is refused instead, naming the file.
+
+A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.
+
+### Command reference
+
+```
+wt step push - Fast-forward target to current branch
+
+Usage: wt step push [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ --no-ff
+ Create a merge commit (no fast-forward)
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Automation:
+ --format <FORMAT>
+ Output format
+
+ JSON prints structured result to stdout after the push completes.
+
+ [default: text]
+ [possible values: text, json]
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ --config-set <toml>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ -v, --verbose...
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+ logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+ apply the same level everywhere — including shell completion, which no flag can reach
+
+ -y, --yes
+ Skip approval prompts
+```
+
## wt step diff
Show all changes since branching. Includes committed, staged, unstaged, and untracked files.
diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.md
index cba3b8754..7781639f4 100644
--- a/skills/worktrunk/reference/merge.md
+++ b/skills/worktrunk/reference/merge.md
@@ -64,10 +64,10 @@ $ wt merge --no-commit --no-rebase
`wt merge` runs these steps:
1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. Skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.
-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
-3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
+3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](https://worktrunk.dev/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](https://worktrunk.dev/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 82fa91d43..631953640 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -26,8 +26,8 @@ $ wt step push
- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](https://worktrunk.dev/llm-commits/)
- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](https://worktrunk.dev/llm-commits/)
-- `rebase` — Rebase onto target branch
-- `push` — Fast-forward target to current branch
+- [`rebase`](#wt-step-rebase) — Rebase onto target branch
+- [`push`](#wt-step-push) — Fast-forward target to current branch
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`eval`](#wt-step-eval) — [experimental] Evaluate a template expression
@@ -282,6 +282,155 @@ Global Options:
Skip approval prompts
```
+## wt step rebase
+
+Rebase onto target.
+
+A rebase puts the branch's commits on top of the target, which is what [`wt step push`](#wt-step-push) needs — a push fast-forwards only if the target is an ancestor of the branch. `wt merge` runs this step as part of its pipeline; on its own it brings a branch up to date with a target that has moved, without merging into it.
+
+The target is any commit: a branch, a tag, a SHA.
+
+### Examples
+
+```bash
+$ wt step rebase # Rebase onto default branch
+$ wt step rebase develop # Rebase onto develop
+$ wt step rebase v1.2.0 # Rebase onto a tag
+```
+
+### Outcomes
+
+The first matching row wins:
+
+| Branch and target | Result |
+|-------------------|--------|
+| The target is already an ancestor of the branch, with no merge commit in between | Nothing runs — `Already up to date` |
+| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` |
+| Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |
+
+A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.
+
+When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](https://worktrunk.dev/merge/) covers why.
+
+### Conflicts
+
+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.
+
+### Command reference
+
+```
+wt step rebase - Rebase onto target
+
+Usage: wt step rebase [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch, tag, or commit
+
+ Defaults to default branch.
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Automation:
+ --format <FORMAT>
+ Output format
+
+ JSON prints structured result to stdout after the rebase completes.
+
+ [default: text]
+ [possible values: text, json]
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ --config-set <toml>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ -v, --verbose...
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+ logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+ apply the same level everywhere — including shell completion, which no flag can reach
+
+ -y, --yes
+ Skip approval prompts
+```
+
+## wt step push
+
+Fast-forward target to current branch.
+
+Despite the name, no commits leave the repository. The target branch's ref moves forward locally, and a worktree holding that branch is updated along with it. Publishing is a separate `git push` to the remote afterward.
+
+The target is a branch, and must already be an ancestor of the current branch. One that has moved ahead is refused, and there is no force variant — [`wt step rebase`](#wt-step-rebase) puts the branch back on top of it first.
+
+### Examples
+
+```bash
+$ wt step push # Fast-forward main to current branch
+$ wt step push develop # Fast-forward develop instead
+$ wt step push --no-ff # Merge commit instead of a fast-forward
+```
+
+### Target worktree
+
+When the target branch has a worktree of its own, that worktree's files move to the new commits too. A fast-forward does both at once, pushing into this repository with `receive.denyCurrentBranch=updateInstead`; `--no-ff` moves the ref first and syncs the worktree after, warning rather than failing if that sync doesn't apply. Uncommitted changes in that worktree are stashed for the duration and restored afterward; one touching a file the push also changes is refused instead, naming the file.
+
+A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.
+
+### Command reference
+
+```
+wt step push - Fast-forward target to current branch
+
+Usage: wt step push [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ --no-ff
+ Create a merge commit (no fast-forward)
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Automation:
+ --format <FORMAT>
+ Output format
+
+ JSON prints structured result to stdout after the push completes.
+
+ [default: text]
+ [possible values: text, json]
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ --config-set <toml>
+ Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+ -v, --verbose...
+ Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+ logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+ apply the same level everywhere — including shell completion, which no flag can reach
+
+ -y, --yes
+ Skip approval prompts
+```
+
## wt step diff
Show all changes since branching. Includes committed, staged, unstaged, and untracked files.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 4e229505b..3357c9698 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1397,10 +1397,10 @@ $ wt merge --no-commit --no-rebase
`wt merge` runs these steps:
1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. Skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.
-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
-3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
+3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](@/step.md#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](@/step.md#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
@@ -1476,8 +1476,8 @@ $ wt step push
- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](@/llm-commits.md)
- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
-- `rebase` — Rebase onto target branch
-- `push` — Fast-forward target to current branch
+- [`rebase`](#wt-step-rebase) — Rebase onto target branch
+- [`push`](#wt-step-push) — Fast-forward target to current branch
- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
- [`eval`](#wt-step-eval) — [experimental] Evaluate a template expression
@@ -1495,6 +1495,8 @@ $ wt step push
- [Aliases](@/extending.md#aliases) — Custom command templates run as `wt <name>`
<!-- subdoc: commit -->
<!-- subdoc: squash -->
+<!-- subdoc: rebase -->
+<!-- subdoc: push -->
<!-- subdoc: diff -->
<!-- subdoc: copy-ignored -->
<!-- subdoc: eval -->
diff --git a/src/cli/step.rs b/src/cli/step.rs
index a4d9d67e5..6be3b7dc4 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -151,18 +151,39 @@ Three sections are printed: the rendered prompt, the shell command that would in
/// Rebase onto target
#[command(
- after_long_help = r#"Rebases the current branch onto the target branch. Conflicts abort immediately; use `git rebase --abort` to recover.
+ after_long_help = r#"A rebase puts the branch's commits on top of the target, which is what [`wt step push`](#wt-step-push) needs — a push fast-forwards only if the target is an ancestor of the branch. `wt merge` runs this step as part of its pipeline; on its own it brings a branch up to date with a target that has moved, without merging into it.
+
+The target is any commit: a branch, a tag, a SHA.
## Examples
```console
$ wt step rebase # Rebase onto default branch
$ wt step rebase develop # Rebase onto develop
+$ wt step rebase v1.2.0 # Rebase onto a tag
```
+
+## Outcomes
+
+The first matching row wins:
+
+| Branch and target | Result |
+|-------------------|--------|
+| The target is already an ancestor of the branch, with no merge commit in between | Nothing runs — `Already up to date` |
+| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` |
+| Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |
+
+A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.
+
+When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](@/merge.md) covers why.
+
+## Conflicts
+
+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.
"#
)]
Rebase {
- /// Target branch
+ /// Target branch, tag, or commit
///
/// Defaults to default branch.
#[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
@@ -177,16 +198,23 @@ $ wt step rebase develop # Rebase onto develop
/// Fast-forward target to current branch
#[command(
- after_long_help = r#"Updates the local target branch to include current commits.
+ after_long_help = r#"Despite the name, no commits leave the repository. The target branch's ref moves forward locally, and a worktree holding that branch is updated along with it. Publishing is a separate `git push` to the remote afterward.
+
+The target is a branch, and must already be an ancestor of the current branch. One that has moved ahead is refused, and there is no force variant — [`wt step rebase`](#wt-step-rebase) puts the branch back on top of it first.
## Examples
```console
$ wt step push # Fast-forward main to current branch
$ wt step push develop # Fast-forward develop instead
+$ wt step push --no-ff # Merge commit instead of a fast-forward
```
-Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updateInstead` internally.
+## Target worktree
+
+When the target branch has a worktree of its own, that worktree's files move to the new commits too. A fast-forward does both at once, pushing into this repository with `receive.denyCurrentBranch=updateInstead`; `--no-ff` moves the ref first and syncs the worktree after, warning rather than failing if that sync doesn't apply. Uncommitted changes in that worktree are stashed for the duration and restored afterward; one touching a file the push also changes is refused instead, naming the file.
+
+A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.
"#
)]
Push {
diff --git a/src/commands/repository_ext.rs b/src/commands/repository_ext.rs
index d41e7c449..7625cc796 100644
--- a/src/commands/repository_ext.rs
+++ b/src/commands/repository_ext.rs
@@ -58,6 +58,10 @@ pub trait RepositoryCliExt {
) -> anyhow::Result<RemoveResult>;
/// Prepare the target worktree for push by auto-stashing non-overlapping changes when safe.
+ ///
+ /// The caller has already established that `target_worktree` exists on disk
+ /// (`MergeContext::prepare` refuses a registered-but-missing worktree), so
+ /// the status read here is free to fail if the directory is gone.
fn prepare_target_worktree(
&self,
target_worktree: Option<&PathBuf>,
@@ -322,11 +326,6 @@ impl RepositoryCliExt for Repository {
return Ok(None);
};
- // Skip if target worktree directory is missing (prunable worktree)
- if !wt_path.exists() {
- return Ok(None);
- }
-
let wt = self.worktree_at(wt_path);
if !wt.is_dirty()? {
return Ok(None);
@@ -411,8 +410,18 @@ impl RepositoryCliExt for Repository {
let Some(merge_base) = self.merge_base("HEAD", target)? else {
return Ok(false);
};
+ // `merge_base` peels an annotated tag to the commit it points at; a bare
+ // `rev-parse` returns the tag object's own SHA. Comparing the two forms
+ // never matches, so an annotated-tag target would always be reported as
+ // needing a rebase — and `wt step rebase <annotated-tag>` would replay
+ // nothing while announcing "Rebased onto <tag>". Peel both sides.
let target_sha = self
- .run_command(&["rev-parse", "--verify", "--end-of-options", target])?
+ .run_command(&[
+ "rev-parse",
+ "--verify",
+ "--end-of-options",
+ &format!("{target}^{{commit}}"),
+ ])?
.trim()
.to_string();
diff --git a/src/commands/worktree/push.rs b/src/commands/worktree/push.rs
index 41d30327a..fa37054af 100644
--- a/src/commands/worktree/push.rs
+++ b/src/commands/worktree/push.rs
@@ -85,9 +85,33 @@ impl MergeContext {
fn prepare(target: Option<&str>, operations: Option<MergeOperations>) -> anyhow::Result<Self> {
let repo = Repository::current()?;
+ // Refuse before reading ancestry: mid-rebase HEAD is detached partway
+ // through the replay, and it *is* a linear extension of the target, so
+ // the fast-forward check below passes and the push carries the target
+ // branch onto a half-replayed history whose worktree still holds
+ // conflict markers — leaving the rebase open behind it.
+ repo.ensure_no_operation_in_progress("push")?;
+
let target_branch = repo.require_target_branch(target)?;
let target_worktree_path = repo.worktree_for_branch(&target_branch)?;
+ // A registered worktree whose directory is gone can't receive the
+ // update, and the two strategies disagreed about that: the
+ // fast-forward pushes with `receive.denyCurrentBranch=updateInstead`,
+ // whose receive-pack cd's into the directory and dies in git plumbing
+ // (`exec 'update-index': cd to '…' failed`), while `--no-ff` moves the
+ // ref with plumbing of its own and skipped the sync. Refusing gives
+ // one answer, and names the `git worktree prune` that clears the
+ // registration.
+ if let Some(path) = &target_worktree_path
+ && !path.exists()
+ {
+ return Err(GitError::WorktreeMissing {
+ branch: target_branch,
+ }
+ .into());
+ }
+
// Snapshot target SHA early for TOCTOU safety (used by both strategies
// for the fast-forward check; --no-ff also uses it for update-ref).
let target_ref = format!("refs/heads/{}", target_branch);
@@ -441,9 +465,7 @@ pub fn handle_no_ff_merge(
// safety). Note: `reset --keep` can't be used here because after
// `update-ref`, HEAD already equals the merge commit, making it a no-op.
// The merge is already done (ref updated), so treat sync failure as a warning.
- if let Some(wt_path) = &ctx.target_worktree_path
- && wt_path.exists()
- {
+ if let Some(wt_path) = &ctx.target_worktree_path {
let target_wt = ctx.repo.worktree_at(wt_path);
if let Err(e) =
target_wt.run_command(&["read-tree", "-m", "-u", &ctx.target_tip, &merge_sha])
diff --git a/src/git/error.rs b/src/git/error.rs
index 0bb158b19..f713cb08a 100644
--- a/src/git/error.rs
+++ b/src/git/error.rs
@@ -405,7 +405,8 @@ pub enum GitError {
action: Option<String>,
},
/// The worktree is partway through a git operation, so a command that
- /// replays commits (`wt merge`, `wt step rebase`) refuses to start.
+ /// rewrites or moves commits (`wt merge`, `wt step rebase`,
+ /// `wt step squash`, `wt step push`) refuses to start.
///
/// Carries no operation and offers no remedy: `git status` names which
/// operation is open and how to finish it, so restating either here only
diff --git a/src/git/repository/mod.rs b/src/git/repository/mod.rs
index 58a224083..63a8006d3 100644
--- a/src/git/repository/mod.rs
+++ b/src/git/repository/mod.rs
@@ -1502,15 +1502,23 @@ impl Repository {
/// Fail when the worktree is already partway through a git operation.
///
- /// A precondition for the commit-replaying commands (`wt step rebase`,
- /// `wt merge`). Mid-rebase, HEAD is detached on a linear extension of the
- /// target, so `is_rebased_onto` — and every
- /// ancestry check like it — reads as "already up to date"; without this
+ /// A precondition for every command that rewrites or moves commits:
+ /// `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge`.
+ /// Mid-rebase, HEAD is detached on a linear extension of the target, so
+ /// `is_rebased_onto` — and every ancestry check like it, including the
+ /// push's fast-forward check — reads as "already up to date"; without this
/// gate a caller reports success over a tree that still holds conflict
- /// markers. The other states are gated for the same reason rather than
- /// their own symptom: a rebase started from any of them either compounds
- /// the half-finished operation or dies inside git with its own plumbing
- /// error, and neither tells the user what to do next.
+ /// markers, or moves the target branch onto one. The other states are gated
+ /// for the same reason rather than their own symptom: an operation started
+ /// from any of them either compounds the half-finished one or dies inside
+ /// git with its own plumbing error, and neither tells the user what to do
+ /// next.
+ ///
+ /// Unresolved conflicts are a separate question, and this is the wrong
+ /// place to ask it: a conflicted `git stash pop` leaves an unmerged index
+ /// with no state file for this check to read. The commands that stage on
+ /// the user's behalf ask the index instead, via
+ /// [`WorkingTree::ensure_no_unmerged_paths`].
///
/// The refusal names no operation, so nothing here has to track what git
/// calls each state or how to leave it; `git status` answers both.
diff --git a/tests/integration_tests/merge.rs b/tests/integration_tests/merge.rs
index 5c9041ae7..1a4335158 100644
--- a/tests/integration_tests/merge.rs
+++ b/tests/integration_tests/merge.rs
@@ -3455,6 +3455,34 @@ fn stop_feature_mid_rebase(repo: &mut TestRepo) -> PathBuf {
feature_wt
}
+/// Leave `feature` stopped mid-rebase with one commit already replayed.
+///
+/// [`stop_feature_mid_rebase`] conflicts on the first pick, which leaves the
+/// detached HEAD *at* main — so a push from there carries nothing and reports
+/// up to date. Only once a pick has landed does the detached HEAD hold commits
+/// a fast-forward would move the target onto.
+fn stop_feature_mid_rebase_after_one_pick(repo: &mut TestRepo) -> PathBuf {
+ let feature_wt = repo.add_worktree("feature");
+ repo.commit_in_worktree(&feature_wt, "clean.txt", "feature\n", "Replays cleanly");
+ repo.commit_in_worktree(&feature_wt, "conflict.txt", "feature\n", "Feature edit");
+ fs::write(repo.root_path().join("conflict.txt"), "main\n").unwrap();
+ repo.run_git(&["add", "conflict.txt"]);
+ repo.run_git(&["commit", "-m", "Main edit"]);
+
+ let rebase = repo
+ .git_command()
+ .current_dir(&feature_wt)
+ .args(["rebase", "main"])
+ .run()
+ .unwrap();
+ assert!(
+ !rebase.status.success(),
+ "rebase should have stopped on the second pick"
+ );
+
+ feature_wt
+}
+
/// Leave `feature` stopped in a conflicted merge, which keeps HEAD on the branch.
fn stop_feature_mid_merge(repo: &mut TestRepo) -> PathBuf {
let feature_wt = feature_conflicting_with_main(repo);
@@ -3608,6 +3636,33 @@ fn test_merge_refuses_unmerged_paths(mut repo: TestRepo) {
);
}
+/// `wt step push` stages nothing, so the index gate above cannot speak for it —
+/// the hazard is HEAD itself. Mid-rebase the detached HEAD is a linear extension
+/// of the target, so the fast-forward check passes and the push moves the target
+/// branch onto a half-replayed history whose worktree still holds conflict
+/// markers, leaving the rebase open behind it.
+#[rstest]
+fn test_step_push_refuses_mid_rebase(mut repo: TestRepo) {
+ let feature_wt = stop_feature_mid_rebase_after_one_pick(&mut repo);
+ // The primary worktree is on main, so its HEAD is main's tip.
+ let main_before = repo.head_sha();
+ assert_ne!(
+ repo.head_sha_in(&feature_wt),
+ main_before,
+ "the detached HEAD has to carry a replayed commit, or the push is a no-op"
+ );
+
+ assert_cmd_snapshot!(
+ "step_push_refuses_mid_rebase",
+ make_snapshot_cmd(&repo, "step", &["push", "main"], Some(&feature_wt))
+ );
+ assert_eq!(
+ repo.head_sha(),
+ main_before,
+ "main must not move while the rebase is open"
+ );
+}
+
// =============================================================================
// JSON output tests
// =============================================================================
@@ -3628,6 +3683,39 @@ fn test_step_rebase_up_to_date_json(mut repo: TestRepo) {
assert_eq!(parsed["target"], "main");
}
+/// An annotated-tag target is peeled before the up-to-date check.
+///
+/// `git merge-base` resolves an annotated tag to the commit it points at, so
+/// comparing it against an unpeeled `rev-parse` never matches: the branch was
+/// reported as needing a rebase, and `wt step rebase <tag>` replayed nothing
+/// while printing "Rebased onto <tag>" and emitting `"outcome": "rebased"`.
+/// The lightweight tag is the single-factor control — same graph, same commit,
+/// and it always took the `up_to_date` path. `test_step_rebase_accepts_tag`
+/// cannot stand in for this: its `git tag v1.0` is lightweight, so its ref
+/// resolves straight to a commit and it passed under the old code too.
+#[rstest]
+fn test_step_rebase_annotated_tag_is_peeled(mut repo: TestRepo) {
+ repo.run_git(&["tag", "-a", "v1.0.0", "-m", "release"]);
+ repo.run_git(&["tag", "v1.0.0-lw"]);
+ let feature_wt = repo.add_worktree_with_commit("feature", "f.txt", "x", "feat: x");
+
+ for tag in ["v1.0.0", "v1.0.0-lw"] {
+ let output = repo
+ .wt_command()
+ .args(["step", "rebase", tag, "--format=json"])
+ .current_dir(&feature_wt)
+ .output()
+ .unwrap();
+ assert!(output.status.success());
+ let parsed: serde_json::Value = serde_json::from_slice(&output.stdout).expect("valid JSON");
+ assert_eq!(
+ parsed["outcome"], "up_to_date",
+ "{tag}: branch already sits on the tagged commit, so nothing should replay"
+ );
+ assert_eq!(parsed["target"], tag);
+ }
+}
+
/// `step rebase --format=json` reports `fast_forwarded` when target advanced cleanly.
#[rstest]
fn test_step_rebase_fast_forwarded_json(mut repo: TestRepo) {
diff --git a/tests/integration_tests/push.rs b/tests/integration_tests/push.rs
index 8aa3e5e3c..3c0440394 100644
--- a/tests/integration_tests/push.rs
+++ b/tests/integration_tests/push.rs
@@ -322,6 +322,52 @@ fn test_push_no_ff_with_submodule_recurse_config(mut repo: TestRepo) {
);
}
+/// A registered target worktree whose directory is gone stops both strategies.
+///
+/// The fast-forward pushes with `receive.denyCurrentBranch=updateInstead`, whose
+/// receive-pack cd's into that directory and died in git plumbing
+/// (`exec 'update-index': cd to '…' failed`) with the ref untouched. `--no-ff`
+/// updates the ref with plumbing of its own and skipped the sync, so it
+/// succeeded over the same broken registration — one command, two answers.
+#[rstest]
+fn test_push_target_worktree_missing(mut repo: TestRepo) {
+ let main_wt = repo.add_main_worktree();
+ let feature_wt =
+ repo.add_worktree_with_commit("feature", "test.txt", "test content", "Add test file");
+ let main_before = main_sha(&repo);
+
+ std::fs::remove_dir_all(&main_wt).unwrap();
+
+ snapshot_push(
+ "push_target_worktree_missing",
+ &repo,
+ &["main"],
+ Some(&feature_wt),
+ );
+ snapshot_push(
+ "push_target_worktree_missing_no_ff",
+ &repo,
+ &["--no-ff", "main"],
+ Some(&feature_wt),
+ );
+ assert_eq!(
+ main_sha(&repo),
+ main_before,
+ "neither strategy may move the ref it cannot sync"
+ );
+}
+
+/// The commit `main` resolves to, read from the repo root.
+fn main_sha(repo: &TestRepo) -> String {
+ let output = repo
+ .git_command()
+ .current_dir(repo.root_path())
+ .args(["rev-parse", "main"])
+ .run()
+ .unwrap();
+ String::from_utf8_lossy(&output.stdout).trim().to_string()
+}
+
#[rstest]
fn test_push_no_remote(#[from(repo_with_feature_worktree)] repo: TestRepo) {
// Note: repo_with_feature_worktree doesn't call setup_remote(), so this tests the "no remote" error case
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
index c6e97222c..a1006fb2d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -164,10 +164,10 @@ $ wt merge --no-commit --no-rebase
`wt merge` runs these steps:
1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. Skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.
-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
-3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
+3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](@/step.md#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](@/step.md#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 4c1213c6a..cb9351b96 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -148,10 +148,10 @@ Preserve the exact clean commit graph and tip:
wt merge runs these steps:
1. Commit — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. Skipped when squashing (the default) — changes are staged during the squash step instead. With --no-squash, this is the only commit step.
-2. Squash — Combines all commits since target into one (like GitHub's "Squash and merge"). Use --stage to control what gets staged: all (default), tracked, or none. A backup ref is saved to refs/wt-backup/<branch>. With --no-squash, individual commits are preserved.
-3. Rebase — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately. With --no-rebase, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
+2. Squash — Combines all commits since target into one (like GitHub's "Squash and merge"). Use --stage to control what gets staged: all (default), tracked, or none. Working-tree changes swept into the squash are backed up first to refs/wt-backup/<branch>. With --no-squash, individual commits are preserved.
+3. Rebase — Rebases onto target, skipping when nothing needs replaying (wt step rebase gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With --no-rebase, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.
4. Pre-merge hooks — Hooks run after rebase, before merge. Failures abort. See wt hook.
-5. Merge — Fast-forward merge to the target branch. With --no-ff, a merge commit is created instead — semi-linear history after the default rebase, while explicit --no-rebase preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
+5. Merge — Fast-forward merge to the target branch (wt step push). With --no-ff, a merge commit is created instead — semi-linear history after the default rebase, while explicit --no-rebase preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.
6. Pre-remove hooks — Hooks run before removing worktree. Failures abort.
7. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. Post-remove + post-merge hooks — Run in background after cleanup.
diff --git a/tests/snapshots/integration__integration_tests__merge__step_push_refuses_mid_rebase.snap b/tests/snapshots/integration__integration_tests__merge__step_push_refuses_mid_rebase.snap
new file mode 100644
index 000000000..d31761dfa
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__merge__step_push_refuses_mid_rebase.snap
@@ -0,0 +1,52 @@
+---
+source: tests/integration_tests/merge.rs
+info:
+ program: wt
+ args:
+ - step
+ - push
+ - main
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLAUDE_CONFIG_DIR: "[TEST_CLAUDE_CONFIG]"
+ 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_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Cannot push: a git operation is already in progress
diff --git a/tests/snapshots/integration__integration_tests__push__push_target_worktree_missing.snap b/tests/snapshots/integration__integration_tests__push__push_target_worktree_missing.snap
new file mode 100644
index 000000000..376bf60ac
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__push__push_target_worktree_missing.snap
@@ -0,0 +1,53 @@
+---
+source: tests/integration_tests/push.rs
+info:
+ program: wt
+ args:
+ - step
+ - push
+ - main
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLAUDE_CONFIG_DIR: "[TEST_CLAUDE_CONFIG]"
+ 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_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Worktree directory missing for main
+↳ To clean up, run git worktree prune
diff --git a/tests/snapshots/integration__integration_tests__push__push_target_worktree_missing_no_ff.snap b/tests/snapshots/integration__integration_tests__push__push_target_worktree_missing_no_ff.snap
new file mode 100644
index 000000000..b5ebe2acc
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__push__push_target_worktree_missing_no_ff.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/push.rs
+info:
+ program: wt
+ args:
+ - step
+ - push
+ - "--no-ff"
+ - main
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLAUDE_CONFIG_DIR: "[TEST_CLAUDE_CONFIG]"
+ 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_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Worktree directory missing for main
+↳ To clean up, run git worktree prune