Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: improve merge command help text clarity (#1783)
worktrunk-bot683327a431fb
diff --git a/docs/content/merge.md b/docs/content/merge.mdindex cb5b956e4..1c6abefb3 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -1,6 +1,6 @@+++title = "wt merge"-description = "Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree."+description = "Merge current branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree."weight = 13[extra]@@ -9,9 +9,9 @@ group = "Commands"<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->-Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree.+Merge current branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree.-Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.+Unlike `git merge`, this merges the current branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The target defaults to the default branch.<figure class="demo"><picture>@@ -62,7 +62,7 @@ wt merge --no-commit`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.+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.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).@@ -71,7 +71,7 @@ wt merge --no-commit7. **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.-Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.+Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.## Local CI@@ -96,9 +96,9 @@ lint = "cargo clippy"## Command reference{% terminal() %}-wt merge - Merge current branch into target+wt merge - Merge current branch into the target branch-Squash & rebase, fast-forward target, remove the worktree.+Squash & rebase, fast-forward the target branch, remove the worktree.Usage: <b><span class=c>wt merge</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.mdindex 6caa2d589..251b48947 100644--- a/skills/worktrunk/reference/merge.md+++ b/skills/worktrunk/reference/merge.md@@ -1,8 +1,8 @@# wt merge-Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree.+Merge current branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree.-Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.+Unlike `git merge`, this merges the current branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The target defaults to the default branch.## Examples@@ -46,7 +46,7 @@ wt merge --no-commit`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.+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.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).@@ -55,7 +55,7 @@ wt merge --no-commit7. **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.-Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.+Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.## Local CI@@ -73,9 +73,9 @@ lint = "cargo clippy"## Command reference-wt merge - Merge current branch into target+wt merge - Merge current branch into the target branch-Squash & rebase, fast-forward target, remove the worktree.+Squash & rebase, fast-forward the target branch, remove the worktree.Usage: <b><span class=c>wt merge</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex cafb683e2..beb6928ef 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -856,11 +856,11 @@ Detached worktrees have no branch name. Pass the worktree path instead: `wt remoforce: bool,},- /// Merge current branch into target+ /// Merge current branch into the target branch///- /// Squash & rebase, fast-forward target, remove the worktree.+ /// Squash & rebase, fast-forward the target branch, remove the worktree.#[command(- after_long_help = r#"Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.+ after_long_help = r#"Unlike `git merge`, this merges the current branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The target defaults to the default branch.<!-- demo: wt-merge.gif 1600x900 -->## Examples@@ -905,7 +905,7 @@ wt merge --no-commit`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.+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.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).@@ -914,7 +914,7 @@ wt merge --no-commit7. **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.-Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.+Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.## Local CIdiff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rsindex 7b1c9415d..a6e3dfb5a 100644--- a/tests/integration_tests/help.rs+++ b/tests/integration_tests/help.rs@@ -150,7 +150,10 @@ fn test_help_list_narrow_terminal() {/// Tests --help-description outputs the meta description for docs frontmatter.#[rstest]#[case("switch", "Switch to a worktree; create if needed.")]-#[case("merge", "Merge current branch into target. Squash & rebase")]+#[case(+ "merge",+ "Merge current branch into the target branch. Squash & rebase"+)]#[case("hook", "Run configured hooks.")]fn test_help_description(#[case] cmd: &str, #[case] expected_prefix: &str) {let output = wt_command()diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snapindex 32388cece..655beabbd 100644--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap@@ -29,9 +29,9 @@ info:success: trueexit_code: 0----- stdout ------wt merge - Merge current branch into target+wt merge - Merge current branch into the target branch-Squash & rebase, fast-forward target, remove the worktree.+Squash & rebase, fast-forward the target branch, remove the worktree.Usage: wt merge [OPTIONS] [TARGET]@@ -85,7 +85,7 @@ Global Options:-v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)-Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.+Unlike `git merge`, this merges the current branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The target defaults to the default branch.<!-- demo: wt-merge.gif 1600x900 -->## Examples@@ -130,7 +130,7 @@ wt merge --no-commit`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.+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.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).@@ -139,7 +139,7 @@ wt merge --no-commit7. **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.-Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.+Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.## Local CIdiff --git a/tests/snapshots/integration__integration_tests__help__help_md_root.snap b/tests/snapshots/integration__integration_tests__help__help_md_root.snapindex 46d369934..6bc6bc83c 100644--- a/tests/snapshots/integration__integration_tests__help__help_md_root.snap+++ b/tests/snapshots/integration__integration_tests__help__help_md_root.snap@@ -10,6 +10,7 @@ info:GIT_EDITOR: ""LANG: CLC_ALL: C+ NO_COLOR: ""PSModulePath: ""RUST_LOG: warnSHELL: ""@@ -35,7 +36,7 @@ Commands:switch Switch to a worktree; create if neededlist List worktrees and their statusremove Remove worktree; delete branch if merged- merge Merge current branch into target+ merge Merge current branch into the target branchstep Run individual operationshook Run configured hooksconfig Manage user & project configsdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex 3ef8c35f1..fbc451805 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap@@ -31,9 +31,9 @@ exit_code: 0----- stdout ---------- stderr ------wt merge - Merge current branch into target[0m+wt merge - Merge current branch into the target branch[0m-Squash & rebase, fast-forward target, remove the worktree.[0m+Squash & rebase, fast-forward the target branch, remove the worktree.[0mUsage: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0m@@ -87,7 +87,7 @@ Usage: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0m[1m[36m-v[0m, [1m[36m--verbose[0m[36m...[0mVerbose output (-v: hooks, templates; -vv: debug report)-Unlike [2mgit merge[0m, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.+Unlike [2mgit merge[0m, this merges the current branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The target defaults to the default branch.[1m[32mExamples[0m@@ -119,7 +119,7 @@ Skip committing/squashing (rebase still runs unless --no-rebase):[2mwt merge[0m runs these steps:-1. [1mCommit[0m — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With [2m--no-squash[0m, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.+1. [1mCommit[0m — 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 [2m--no-squash[0m, this is the only commit step.2. [1mSquash[0m — Combines all commits since target into one (like GitHub's "Squash and merge"). Use [2m--stage[0m to control what gets staged: [2mall[0m (default), [2mtracked[0m, or [2mnone[0m. A backup ref is saved to [2mrefs/wt-backup/<branch>[0m. With [2m--no-squash[0m, individual commits are preserved.3. [1mRebase[0m — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.4. [1mPre-merge hooks[0m — Hooks run after rebase, before merge. Failures abort. See [2mwt hook[0m.@@ -128,7 +128,7 @@ Skip committing/squashing (rebase still runs unless --no-rebase):7. [1mCleanup[0m — Removes the worktree and branch. Use [2m--no-remove[0m to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.8. [1mPost-remove + post-merge hooks[0m — Run in background after cleanup.-Use [2m--no-commit[0m to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless [2m--no-rebase[0m is passed. Useful after preparing commits manually with [2mwt step[0m. Requires a clean working tree.+Use [2m--no-commit[0m to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless [2m--no-rebase[0m is passed. Useful after preparing commits manually with [2mwt step commit[0m. Requires a clean working tree.[1m[32mLocal CI[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap b/tests/snapshots/integration__integration_tests__help__help_merge_short.snapindex 7961f4038..473d06193 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap@@ -31,7 +31,7 @@ exit_code: 0----- stdout ---------- stderr ------wt merge - Merge current branch into target+wt merge - Merge current branch into the target branchUsage: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snapindex 89ca485a3..e829e785b 100644--- a/tests/snapshots/integration__integration_tests__help__help_no_args.snap+++ b/tests/snapshots/integration__integration_tests__help__help_no_args.snap@@ -9,6 +9,7 @@ info:GIT_EDITOR: ""LANG: CLC_ALL: C+ NO_COLOR: ""PSModulePath: ""RUST_LOG: warnSHELL: ""@@ -36,7 +37,7 @@ Usage: [1m[36mwt[0m [36m[OPTIONS][0m [36m[COMMAND][0m[1m[36mswitch[0m Switch to a worktree; create if needed[1m[36mlist[0m List worktrees and their status[1m[36mremove[0m Remove worktree; delete branch if merged- [1m[36mmerge[0m Merge current branch into target+ [1m[36mmerge[0m Merge current branch into the target branch[1m[36mstep[0m Run individual operations[1m[36mhook[0m Run configured hooks[1m[36mconfig[0m Manage user & project configsdiff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snapindex bcafe06ba..34a5517c3 100644--- a/tests/snapshots/integration__integration_tests__help__help_root_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_root_long.snap@@ -10,6 +10,7 @@ info:GIT_EDITOR: ""LANG: CLC_ALL: C+ NO_COLOR: ""PSModulePath: ""RUST_LOG: warnSHELL: ""@@ -37,7 +38,7 @@ Usage: [1m[36mwt[0m [36m[OPTIONS][0m [36m[COMMAND][0m[1m[36mswitch[0m Switch to a worktree; create if needed[1m[36mlist[0m List worktrees and their status[1m[36mremove[0m Remove worktree; delete branch if merged- [1m[36mmerge[0m Merge current branch into target+ [1m[36mmerge[0m Merge current branch into the target branch[1m[36mstep[0m Run individual operations[1m[36mhook[0m Run configured hooks[1m[36mconfig[0m Manage user & project configsdiff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snapindex a69fd2a42..ce1a76062 100644--- a/tests/snapshots/integration__integration_tests__help__help_root_short.snap+++ b/tests/snapshots/integration__integration_tests__help__help_root_short.snap@@ -10,6 +10,7 @@ info:GIT_EDITOR: ""LANG: CLC_ALL: C+ NO_COLOR: ""PSModulePath: ""RUST_LOG: warnSHELL: ""@@ -37,7 +38,7 @@ Usage: [1m[36mwt[0m [36m[OPTIONS][0m [36m[COMMAND][0m[1m[36mswitch[0m Switch to a worktree; create if needed[1m[36mlist[0m List worktrees and their status[1m[36mremove[0m Remove worktree; delete branch if merged- [1m[36mmerge[0m Merge current branch into target+ [1m[36mmerge[0m Merge current branch into the target branch[1m[36mstep[0m Run individual operations[1m[36mhook[0m Run configured hooks[1m[36mconfig[0m Manage user & project configs