Skip to content

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.md
index 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-commit
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.
-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 &amp; rebase, fast-forward target, remove the worktree.
+Squash &amp; 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.md
index 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-commit
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.
-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 &amp; rebase, fast-forward target, remove the worktree.
+Squash &amp; 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.rs
index 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 remo
force: 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-commit
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.
-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
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index 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.snap
index 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: true
exit_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-commit
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.
-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
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_root.snap b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
index 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: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -35,7 +36,7 @@ Commands:
switch Switch to a worktree; create if needed
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge current branch into target
+ merge Merge current branch into the target branch
step Run individual operations
hook Run configured hooks
config Manage user & project configs
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 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
+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]
@@ -87,7 +87,7 @@ Usage: wt merge [OPTIONS] [TARGET]
-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.
Examples
@@ -119,7 +119,7 @@ Skip committing/squashing (rebase still runs unless --no-rebase):
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.
@@ -128,7 +128,7 @@ Skip committing/squashing (rebase still runs unless --no-rebase):
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.
-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
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
index 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 branch
Usage: wt merge [OPTIONS] [TARGET]
diff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
index 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: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -36,7 +37,7 @@ Usage: wt [OPTIONS] [COMMAND]
switch Switch to a worktree; create if needed
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge current branch into target
+ merge Merge current branch into the target branch
step Run individual operations
hook Run configured hooks
config Manage user & project configs
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
index 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: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -37,7 +38,7 @@ Usage: wt [OPTIONS] [COMMAND]
switch Switch to a worktree; create if needed
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge current branch into target
+ merge Merge current branch into the target branch
step Run individual operations
hook Run configured hooks
config Manage user & project configs
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
index 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: C
LC_ALL: C
+ NO_COLOR: ""
PSModulePath: ""
RUST_LOG: warn
SHELL: ""
@@ -37,7 +38,7 @@ Usage: wt [OPTIONS] [COMMAND]
switch Switch to a worktree; create if needed
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge current branch into target
+ merge Merge current branch into the target branch
step Run individual operations
hook Run configured hooks
config Manage user & project configs