Skip to content

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

Clarify merge pipeline and simplify --no-commit behavior

Maximilian Roosad63696bd6b0
diff --git a/docs/content/hooks.md b/docs/content/hooks.md
index 280f36e8a..f21740832 100644
--- a/docs/content/hooks.md
+++ b/docs/content/hooks.md
@@ -175,20 +175,13 @@ post-merge = "cargo install --path ."
- Runs after push succeeds, before cleanup
- Failures show errors but cleanup proceeds
-## Execution order during merge
-
-The complete sequence when running `wt merge`:
-
-1. Validate working tree is clean
-2. **Run `pre-commit`** — fail-fast, aborts if any command fails
-3. Create commit (with LLM message if configured)
-4. Switch to main worktree
-5. Pull latest changes
-6. **Run `pre-merge`** — fail-fast, aborts if any command fails
-7. Merge branch into target
-8. Push to remote
-9. **Run `post-merge`** — best-effort, failures logged
-10. Clean up (delete branch, remove worktree)
+## When hooks run during merge
+
+- **pre-commit** — After staging, before squash commit
+- **pre-merge** — After rebase, before merge to target
+- **post-merge** — After cleanup completes
+
+See [wt merge](@/merge.md#pipeline) for the complete pipeline.
## Security & approval
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 3b37cf63f..fc680d055 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -20,6 +20,12 @@ Basic merge to main:
wt merge
```
+Merge to a different branch:
+
+```bash
+wt merge develop
+```
+
Keep the worktree after merging:
```bash
@@ -42,21 +48,14 @@ wt merge --no-commit
`wt merge` runs these steps:
-1. **Commit** — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`.
-
-2. **Squash** — Combines all commits into one (like GitHub's "Squash and merge"). Skip with `--no-squash` to preserve individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-
-3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-
-4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](@/hooks.md).
-
-5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-
-6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
-
-7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+1. **Squash** — Stages uncommitted changes, then 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`, uncommitted changes are committed separately and individual commits are preserved.
+2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
+3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [Hooks](@/hooks.md).
+4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
+5. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+6. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
-Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
+Use `--no-commit` to skip all git operations (steps 1-2) and only run hooks and merge. Useful after preparing commits manually with `wt step`. Requires a clean working tree.
## See also
diff --git a/src/cli.rs b/src/cli.rs
index cf989a0b8..bf22b879f 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1180,6 +1180,12 @@ Basic merge to main:
wt merge
```
+Merge to a different branch:
+
+```console
+wt merge develop
+```
+
Keep the worktree after merging:
```console
@@ -1202,21 +1208,14 @@ wt merge --no-commit
`wt merge` runs these steps:
-1. **Commit** — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`.
-
-2. **Squash** — Combines all commits into one (like GitHub's "Squash and merge"). Skip with `--no-squash` to preserve individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-
-3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-
-4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](@/hooks.md).
-
-5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-
-6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
-
-7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+1. **Squash** — Stages uncommitted changes, then 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`, uncommitted changes are committed separately and individual commits are preserved.
+2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
+3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [Hooks](@/hooks.md).
+4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
+5. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+6. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
-Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
+Use `--no-commit` to skip all git operations (steps 1-2) and only run hooks and merge. Useful after preparing commits manually with `wt step`. Requires a clean working tree.
## See also
diff --git a/src/commands/merge.rs b/src/commands/merge.rs
index 7d003d545..c04ec9e06 100644
--- a/src/commands/merge.rs
+++ b/src/commands/merge.rs
@@ -1,8 +1,6 @@
-use color_print::cformat;
use worktrunk::HookType;
use worktrunk::config::{Command, CommandPhase, ProjectConfig};
use worktrunk::git::Repository;
-use worktrunk::styling::{ERROR_EMOJI, HINT_EMOJI};
use super::command_approval::approve_command_batch;
use super::command_executor::CommandContext;
@@ -91,18 +89,7 @@ pub fn handle_merge(
.into());
}
- // Validate --no-commit flag compatibility
- if !commit && remove {
- return Err(anyhow::anyhow!(
- "{}\n\n{}",
- cformat!("{ERROR_EMOJI} <red>--no-commit requires --no-remove</>"),
- cformat!(
- "{HINT_EMOJI} <dim>Cannot remove active worktree when skipping commit/rebase</>"
- )
- ));
- }
-
- // --no-commit implies --no-squash (validation above ensures --no-remove is already set)
+ // --no-commit implies --no-squash
let squash_enabled = squash && commit;
// Get target branch (default to default branch if not provided)
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 b02dbf9e3..74a21f3c3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -73,6 +73,10 @@ Basic merge to main:
wt merge
+Merge to a different branch:
+
+ wt merge develop
+
Keep the worktree after merging:
wt merge --no-remove
@@ -89,21 +93,14 @@ Skip git operations, only run hooks and push:
wt merge runs these steps:
-1. Commit — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use --stage to control what gets staged: all (default), tracked, or none.
-
-2. Squash — Combines all commits into one (like GitHub's "Squash and merge"). Skip with --no-squash to preserve individual commits. A backup ref is saved to refs/wt-backup/<branch>.
-
-3. Rebase — Rebases onto the target branch. Conflicts abort immediately.
-
-4. Pre-merge hooks — Project commands run after rebase, before push. Failures abort. See Hooks.
-
-5. Push — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-
-6. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree.
-
-7. Post-merge hooks — Project commands run after cleanup. Failures are logged but don't abort.
+1. Squash — Stages uncommitted changes, then 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, uncommitted changes are committed separately and individual commits are preserved.
+2. Rebase — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
+3. Pre-merge hooks — Project commands run after rebase, before merge. Failures abort. See Hooks.
+4. Merge — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
+5. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree.
+6. Post-merge hooks — Project commands run after cleanup. Failures are logged but don't abort.
-Use --no-commit to skip steps 1-3 and only run hooks and push. Requires a clean working tree and --no-remove.
+Use --no-commit to skip all git operations (steps 1-2) and only run hooks and merge. Useful after preparing commits manually with wt step. Requires a clean working tree.
See also