Skip to content

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

Refactor documentation and CLI help text

Maximilian Roos47df9b864fe4
diff --git a/docs/content/faq.md b/docs/content/faq.md
index e167955bf..87397aa87 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -92,9 +92,9 @@ Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, r
Worktrunk checks the local git cache first, queries the remote if needed, and falls back to local inference when no remote exists. The result is cached for fast subsequent lookups.
-If your remote's default branch has changed (e.g., renamed from master to main), refresh with `wt config cache refresh`.
+If the remote's default branch has changed (e.g., renamed from master to main), refresh with `wt config state default-branch get --refresh`.
-For full details on the detection mechanism, see `wt config cache --help`.
+For full details on the detection mechanism, see `wt config state default-branch --help`.
## On Windows, `wt` conflicts with Windows Terminal
diff --git a/docs/content/merge.md b/docs/content/merge.md
index ca4debe53..17799049e 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -8,8 +8,6 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
-When already on the target branch or in the main worktree, the worktree is preserved automatically.
-
## Examples
Basic merge to main:
@@ -46,12 +44,12 @@ wt merge --no-commit
`wt merge` runs these steps:
-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.
+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 become a separate commit 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 [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
-6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
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.
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 46d944510..cd5262eb9 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -30,7 +30,7 @@ When the target branch has no worktree, worktrunk:
3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
+The `--create` flag creates a new branch from `--base` (defaults to the repository's default branch). Without `--create`, the branch must already exist.
```bash
wt switch feature # Existing branch → creates worktree
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 522751dab..2c38af5b4 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -39,7 +39,7 @@ See [Worktrunk's own `.config/wt.toml`](https://github.com/max-sixty/worktrunk/b
"test" = "uv run pytest"
```
-This catches issues locally before pushing — like having CI run on your machine.
+This catches issues locally before pushing — like running CI locally.
## Track agent status
diff --git a/src/cli.rs b/src/cli.rs
index 22a348311..ac2fb15d5 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2101,7 +2101,7 @@ When the target branch has no worktree, worktrunk:
3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
+The `--create` flag creates a new branch from `--base` (defaults to the repository's default branch). Without `--create`, the branch must already exist.
```console
wt switch feature # Existing branch → creates worktree
@@ -2277,10 +2277,7 @@ Removal runs in the background by default (returns immediately). Logs are writte
/// Merge worktree into target branch
///
/// Squashes commits, rebases, runs hooks, merges to target, and removes the worktree.
- #[command(
- after_long_help = r#"When already on the target branch or in the main worktree, the worktree is preserved automatically.
-
-## Examples
+ #[command(after_long_help = r#"## Examples
Basic merge to main:
@@ -2316,12 +2313,12 @@ wt merge --no-commit
`wt merge` runs these steps:
-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.
+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 become a separate commit 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 [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
-6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
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.
@@ -2331,8 +2328,7 @@ Use `--no-commit` to skip all git operations (steps 1-2) and only run hooks and
- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
- [wt remove](@/remove.md) — Remove worktrees without merging
- [wt switch](@/switch.md) — Navigate to other worktrees
-"#
- )]
+"#)]
Merge {
/// Target branch
///
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 78d4dd538..221584051 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -67,8 +67,6 @@ Global Options:
-v, --verbose
Show commands and debug info
-When already on the target branch or in the main worktree, the worktree is preserved automatically.
-
## Examples
Basic merge to main:
@@ -107,12 +105,13 @@ wt merge --no-commit
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.
+changes become a separate commit 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 [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
-6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree,
+the worktree is preserved.
7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
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`.
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 90064a93e..62f63854f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -69,8 +69,6 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose
Show commands and debug info
-When already on the target branch or in the main worktree, the worktree is preserved automatically.
-
Examples
Basic merge to main:
@@ -99,12 +97,13 @@ Skip git operations, only run hooks and push:
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.
+changes become a separate commit 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 wt hook.
4. Merge — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
5. Pre-remove hooks — Project commands run before removing worktree. Failures abort.
-6. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree.
+6. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree. When already on the target branch or in the main worktree,
+the worktree is preserved.
7. Post-merge hooks — Project commands run after cleanup. Failures are logged but don't abort.
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.
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
index 063c47ade..be30d41c3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
@@ -17,8 +17,6 @@ exit_code: 0
----- stdout -----
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
-When already on the target branch or in the main worktree, the worktree is preserved automatically.
-
## Examples
Basic merge to main:
@@ -55,12 +53,12 @@ wt merge --no-commit
`wt merge` runs these steps:
-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.
+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 become a separate commit 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 [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
-6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
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.
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
index 9d7498f9e..714e76290 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -39,7 +39,7 @@ When the target branch has no worktree, worktrunk:
3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
+The `--create` flag creates a new branch from `--base` (defaults to the repository's default branch). Without `--create`, the branch must already exist.
```bash
wt switch feature # Existing branch → creates worktree
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 0dda55286..14c55dbc7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -90,7 +90,8 @@ When the target branch has no worktree, worktrunk:
3. Runs post-create hooks (blocking)
4. Spawns post-start hooks (background)
-The --create flag creates a new branch from the --base branch (defaults to default branch). Without --create, the branch must already exist.
+The --create flag creates a new branch from --base (defaults to the repository's default branch). Without --create, the branch must already
+exist.
wt switch feature # Existing branch → creates worktree
wt switch --create feature # New branch and worktree