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.mdindex 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, rWorktrunk 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 Terminaldiff --git a/docs/content/merge.md b/docs/content/merge.mdindex 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.-## ExamplesBasic 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.mdindex 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.```bashwt switch feature # Existing branch → creates worktreediff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 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 statusdiff --git a/src/cli.rs b/src/cli.rsindex 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.```consolewt 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#"## ExamplesBasic 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.snapindex 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, --verboseShow commands and debug info-When already on the target branch or in the main worktree, the worktree is preserved automatically.-## ExamplesBasic merge to main:@@ -107,12 +105,13 @@ wt merge --no-commit1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` tocontrol 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.snapindex 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: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][1m[36m-v[0m, [1m[36m--verboseShow commands and debug info-When already on the target branch or in the main worktree, the worktree is preserved automatically.-[32mExamplesBasic merge to main:@@ -99,12 +97,13 @@ Skip git operations, only run hooks and push:1. [1mSquash[0m — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use [2m--stage[0m tocontrol 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, uncommitted-changes are committed separately and individual commits are preserved.+changes become a separate commit and individual commits are preserved.2. [1mRebase[0m — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.3. [1mPre-merge hooks[0m — Project commands run after rebase, before merge. Failures abort. See wt hook.4. [1mMerge[0m — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.5. [1mPre-remove hooks[0m — Project commands run before removing worktree. Failures abort.-6. [1mCleanup[0m — Removes the worktree and branch. Use [2m--no-remove[0m to keep the worktree.+6. [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 main worktree,+the worktree is preserved.7. [1mPost-merge hooks[0m — Project commands run after cleanup. Failures are logged but don't abort.Use [2m--no-commit[0m to skip all git operations (steps 1-2) and only run hooks and merge. Useful after preparing commits manually with [2mwt step[0m.diff --git a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap b/tests/snapshots/integration__integration_tests__help__help_page_merge.snapindex 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.-## ExamplesBasic 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.snapindex 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.```bashwt switch feature # Existing branch → creates worktreediff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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 [2m--create[0m flag creates a new branch from the [2m--base[0m branch (defaults to default branch). Without [2m--create[0m, the branch must already exist.+The [2m--create[0m flag creates a new branch from [2m--base[0m (defaults to the repository's default branch). Without [2m--create[0m, the branch must already+exist.[2mwt switch feature # Existing branch → creates worktree[2mwt switch --create feature # New branch and worktree