Skip to content

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

Standardize doc headings to sentence case (#89)

Maximilian Roosb4d026822f0d
diff --git a/README.md b/README.md
index 867c41584..7443d681a 100644
--- a/README.md
+++ b/README.md
@@ -521,7 +521,7 @@ wt switch --create hotfix --base production
For interactive selection, use [`wt select`](@/select.md).
-### Creating Worktrees
+### Creating worktrees
With `--create`, worktrunk:
@@ -552,7 +552,7 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
-### Path-First Lookup
+### Path-first lookup
Arguments resolve by checking the filesystem before git branches:
@@ -564,7 +564,7 @@ Arguments resolve by checking the filesystem before git branches:
- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)
- `wt switch bar` → also works (branch lookup finds same worktree)
-### See Also
+### See also
- [wt select](@/select.md) — Interactive worktree selection
- [wt list](@/list.md) — View all worktrees
@@ -679,7 +679,7 @@ wt merge --no-commit
Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
-### See Also
+### See also
- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
- [wt remove](@/remove.md) — Remove worktrees without merging
@@ -756,19 +756,19 @@ Force-delete an unmerged branch:
wt remove -D experimental
```
-### Branch Cleanup
+### Branch cleanup
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
-### Background Removal
+### Background removal
Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
Arguments resolve by path first, then branch name—see [wt switch](@/switch.md#path-first-lookup). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).
-### See Also
+### See also
- [wt merge](@/merge.md) — Remove worktree after merging
- [wt list](@/list.md) — View all worktrees
@@ -887,7 +887,7 @@ The CI column shows GitHub/GitLab pipeline status:
Any CI dot appears dimmed when there are unpushed local changes (stale status).
-### Status Symbols
+### Status symbols
Symbols appear in the Status column in this order:
@@ -914,7 +914,7 @@ Symbols appear in the Status column in this order:
Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-### JSON Output
+### JSON output
Query structured data with `--format=json`:
@@ -944,7 +944,7 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
- `is_current` — Current directory
- `is_previous` — Previous worktree from [wt switch](@/switch.md)
-### See Also
+### See also
- [wt select](@/select.md) — Interactive worktree picker with live preview
@@ -1007,7 +1007,7 @@ Show current configuration and file locations:
wt config show
```
-### Shell Integration
+### Shell integration
Shell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.
@@ -1024,7 +1024,7 @@ eval "$(wt config shell init zsh)"
wt config shell init fish | source
```
-### Configuration Files
+### Configuration files
**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):
@@ -1034,7 +1034,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.
-### LLM Commit Messages
+### LLM commit messages
Worktrunk can generate commit messages using an LLM. Enable in user config:
@@ -1128,7 +1128,7 @@ wt step push
- `pre-merge` — Before pushing to target
- `post-merge` — After merge cleanup
-### See Also
+### See also
- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 9e3fb4be6..a9a602128 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -1,6 +1,6 @@
# Docs Site
-## Demo GIF Workflow
+## Demo GIF workflow
See `dev/wt-demo/CLAUDE.md` for the full workflow. Quick reference:
@@ -23,7 +23,7 @@ This is an initial scaffolding of the documentation site. The content was auto-g
This is being merged to enable iteration, not as finished documentation.
-## Development Workflow
+## Development workflow
When making changes to the docs, **ensure the dev server is running before returning to the user** so they can review changes in their browser.
@@ -34,7 +34,7 @@ cd docs && zola serve
If the server isn't already running, start it as a background process or in a separate terminal session before completing work. The user should be able to immediately see rendered changes without needing to manually start the server.
-### Visual Review Requirement
+### Visual review requirement
**Always verify changes visually before returning to the user.** Use Playwright MCP (or similar browser automation) to:
@@ -57,7 +57,7 @@ Common issues to check:
View changes: http://127.0.0.1:1111
```
-## Theme Architecture
+## Theme architecture
The docs use a "warm workbench" theme built on top of the Juice Zola theme. Key files:
@@ -69,7 +69,7 @@ The docs use a "warm workbench" theme built on top of the Juice Zola theme. Key
| `templates/index.html` | Homepage hero and animations |
| `templates/page.html` | Doc page TOC rendering |
-### Layout System
+### Layout system
The sticky header and TOC use **definitional CSS variables** so positions are always in sync:
@@ -83,7 +83,7 @@ Anchor scroll-margin: same calculation
When either variable changes (including via media queries), all dependent values update automatically. This prevents the TOC from "jumping" when transitioning to sticky mode.
-### Key Technical Decisions
+### Key technical decisions
1. **`box-sizing: border-box` on header** - Border is included in height, simplifying calculations
2. **`scrollbar-gutter: stable`** - Reserves scrollbar space to prevent layout shift on navigation
@@ -91,25 +91,25 @@ When either variable changes (including via media queries), all dependent values
4. **Logo preload** - Prevents flash when navigating between pages
5. **WCAG AA colors** - `--wt-color-text-soft` is #78716a for 4.5:1 contrast
-### Responsive Breakpoints
+### Responsive breakpoints
Variables are overridden in media queries to maintain definitional correctness:
- **≤1024px**: `--wt-main-padding-top: 30px`
- **≤768px**: `--wt-header-height: 50px`, `--wt-main-padding-top: 20px`, TOC hidden
-### Extending the Theme
+### Extending the theme
When adding new positioned elements:
- Use the layout variables rather than hardcoding pixel values
- Test anchor navigation to verify no visual jumps
- Check both with and without page scroll
-## Command Documentation
+## Command documentation
Command pages (e.g., `switch.md`, `merge.md`, `list.md`) are **generated from the CLI source code**. The **entire file** is generated — manual edits will be overwritten.
-### Generation Mechanism
+### Generation mechanism
Each command page is generated by running:
@@ -122,7 +122,7 @@ The output combines:
2. **Conceptual documentation** — from `after_long_help` in `src/cli.rs`
3. **Command Reference section** — the standard `--help` output
-### Editing Command Docs
+### Editing command docs
**To update command documentation, edit `src/cli.rs`**, not the markdown files directly.
@@ -135,7 +135,7 @@ After editing, run the sync test (which auto-updates out-of-sync pages):
cargo test --test integration test_command_pages_are_in_sync
```
-### Example Output Expansion (wt list)
+### Example output expansion (wt list)
The `wt list` examples use **HTML comments + code blocks** that expand to full snapshot output. In `cli.rs`, you write:
@@ -178,7 +178,7 @@ This renders differently in each context:
The examples in `cli.rs` are just command stubs — the actual output comes from snapshots generated by integration tests. This ensures docs always match real CLI behavior.
-### CLI and Web Compatibility
+### CLI and web compatibility
Content in `after_long_help` must work in **both** the terminal (`--help`) and the web docs:
@@ -187,7 +187,7 @@ Content in `after_long_help` must work in **both** the terminal (`--help`) and t
- **Code blocks** — Work in both
- **Raw HTML** — Avoid. Renders as raw text in terminal help.
-### Post-Processing for Web Docs
+### Post-processing for web docs
The `--help-page` generator in `src/main.rs` applies post-processing to transform CLI-friendly content into web-friendly HTML:
diff --git a/docs/content/advanced.md b/docs/content/advanced.md
index ae39df48c..17b6238d3 100644
--- a/docs/content/advanced.md
+++ b/docs/content/advanced.md
@@ -8,7 +8,7 @@ group = "Reference"
Most Worktrunk users get everything they need from `wt switch`, `wt list`, `wt merge`, and `wt remove`. The features below are optional power-user capabilities.
-## Claude Code Integration
+## Claude Code integration
Worktrunk includes a Claude Code plugin for tracking agent status across worktrees.
@@ -51,7 +51,7 @@ $ wt config var set marker "✅" --branch feature # Specific branch
$ git config worktrunk.marker.feature "💬" # Direct git config
```
-## Statusline Integration
+## Statusline integration
`wt list statusline` outputs a single-line status for shell prompts, starship, or editor integrations.[^1]
@@ -76,7 +76,7 @@ Add to `~/.claude/settings.json`:
}
```
-## Interactive Worktree Picker
+## Interactive worktree picker
`wt select` opens a fuzzy-search worktree picker with diff preview (Unix only).
diff --git a/docs/content/config.md b/docs/content/config.md
index 4f754d2b1..217a4f6f8 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -30,7 +30,7 @@ Show current configuration and file locations:
wt config show
```
-## Shell Integration
+## Shell integration
Shell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.
@@ -47,7 +47,7 @@ eval "$(wt config shell init zsh)"
wt config shell init fish | source
```
-## Configuration Files
+## Configuration files
**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):
@@ -57,7 +57,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.
-## LLM Commit Messages
+## LLM commit messages
Worktrunk can generate commit messages using an LLM. Enable in user config:
@@ -70,7 +70,7 @@ See [LLM Commits](@/llm-commits.md) for installation, provider setup, and custom
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit cli.rs to update -->
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index 890e3bc65..0c5cc3339 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -13,7 +13,7 @@ Worktrunk uses two configuration files:
| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |
| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |
-## User Config
+## User config
The user config stores personal preferences that apply across all repositories. Create it with:
@@ -23,7 +23,7 @@ wt config create
This creates `~/.config/worktrunk/config.toml` with documented examples. View the current configuration with `wt config show`.
-### Worktree Path Template
+### Worktree path template
Controls where new worktrees are created. The template is relative to the repository root:
@@ -42,7 +42,7 @@ worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
- `{{ main_worktree }}` — main worktree directory name
- `{{ branch }}` — branch name (slashes replaced with dashes)
-### Command Defaults
+### Command defaults
Override default flag behavior for commands. Settings here apply unless explicitly overridden on the command line.
@@ -73,7 +73,7 @@ remove = false # --no-remove: keep worktree after merge
verify = false # --no-verify: skip project hooks
```
-### LLM Commit Messages
+### LLM commit messages
Configure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):
@@ -85,7 +85,7 @@ args = ["-m", "claude-haiku-4.5"]
See [LLM Commit Messages](@/llm-commits.md) for setup details and template customization.
-### Approved Commands
+### Approved commands
When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:
@@ -99,7 +99,7 @@ approved-commands = [
Manage approvals with `wt config approvals list` and `wt config approvals clear <repo>`.
-## Project Config
+## Project config
The project config defines lifecycle hooks — commands that run at specific points during worktree operations. This file is checked into version control and shared across the team.
@@ -116,7 +116,7 @@ lint = "npm run lint"
See [Hooks](@/hooks.md) for complete documentation on hook types, execution order, and template variables.
-## Shell Integration
+## Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -136,7 +136,7 @@ wt config shell init fish | source
Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
-## Environment Variables
+## Environment variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 6f83792d2..3be2fd952 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -41,7 +41,7 @@ Use `--force` to bypass prompts (useful for CI/automation).
## How does Worktrunk compare to alternatives?
-### vs. Branch Switching
+### vs. branch switching
Branch switching uses one directory, so only one agent can work at a time. Worktrees give each agent its own directory.
diff --git a/docs/content/hooks.md b/docs/content/hooks.md
index 3a1a97522..9c6c100b3 100644
--- a/docs/content/hooks.md
+++ b/docs/content/hooks.md
@@ -8,7 +8,7 @@ group = "Reference"
Hooks automate setup and validation at worktree lifecycle events. They're defined in `.config/wt.toml` (project config) and run automatically during `wt switch --create` and `wt merge`.
-## Hook Types
+## Hook types
| Hook | When | Blocking? | Fail-Fast? | Execution |
|------|------|-----------|------------|-----------|
@@ -21,23 +21,23 @@ Hooks automate setup and validation at worktree lifecycle events. They're define
**Blocking**: Command waits for hook to complete before continuing.
**Fail-fast**: First failure aborts the operation.
-## Configuration Formats
+## Configuration formats
All hooks support three formats in `.config/wt.toml`:
-### Single Command (String)
+### Single command (string)
```toml
post-create = "npm install"
```
-### Multiple Commands (Array)
+### Multiple commands (array)
```toml
post-create = ["npm install", "npm run build"]
```
-### Named Commands (Table)
+### Named commands (table)
```toml
[post-create]
@@ -63,11 +63,11 @@ Named commands appear in output with their labels:
<!-- END AUTO-GENERATED -->
-## Template Variables
+## Template variables
Hooks can use template variables that expand at runtime:
-### Basic Variables (All Hooks)
+### Basic variables (all hooks)
- `{{ repo }}` — Repository name (e.g., "my-project")
- `{{ branch }}` — Branch name (slashes replaced with dashes)
@@ -76,14 +76,14 @@ Hooks can use template variables that expand at runtime:
- `{{ repo_root }}` — Absolute path to the repository root
- `{{ default_branch }}` — Default branch name (e.g., "main")
-### Git Variables (All Hooks)
+### Git variables (all hooks)
- `{{ commit }}` — Current HEAD commit SHA (full 40-character hash)
- `{{ short_commit }}` — Current HEAD commit SHA (short 7-character hash)
- `{{ remote }}` — Primary remote name (e.g., "origin")
- `{{ upstream }}` — Upstream tracking branch (e.g., "origin/feature"), if configured
-### Merge Variables (pre-commit, pre-merge, post-merge)
+### Merge variables (pre-commit, pre-merge, post-merge)
- `{{ target }}` — Target branch for the merge (e.g., "main")
@@ -95,7 +95,7 @@ post-create = "echo '{{ short_commit }}' > .version"
pre-merge = "echo 'Merging {{ branch }} into {{ target }}'"
```
-## Hook Details
+## Hook details
### post-create
@@ -181,7 +181,7 @@ post-merge = "cargo install --path ."
- Runs after push succeeds, before cleanup
- Failures show errors but cleanup proceeds
-## Execution Order During Merge
+## Execution order during merge
The complete sequence when running `wt merge`:
@@ -196,7 +196,7 @@ The complete sequence when running `wt merge`:
9. **Run `post-merge`** — best-effort, failures logged
10. Clean up (delete branch, remove worktree)
-## Security & Approval
+## Security & approval
Project commands require approval on first run. When a project defines hooks, the first execution prompts for approval:
@@ -231,7 +231,7 @@ wt config approvals list # Show all approvals
wt config approvals clear <repo> # Remove approvals for a repo
```
-## Skipping Hooks
+## Skipping hooks
Use `--no-verify` to skip all project hooks:
@@ -251,7 +251,7 @@ Background operations log to `.git/wt-logs/` in the main worktree:
Logs overwrite on repeated runs for the same branch/operation. Stale logs from deleted branches persist but are bounded by branch count.
-## Running Hooks Manually
+## Running hooks manually
Use `wt step` to run individual hooks:
@@ -261,7 +261,7 @@ wt step pre-merge # Run pre-merge hooks
wt step post-merge # Run post-merge hooks
```
-## Example Configurations
+## Example configurations
### Node.js / TypeScript
@@ -343,9 +343,9 @@ backend-tests = "cd backend && cargo test"
integration = "./scripts/integration-tests.sh"
```
-## Common Patterns
+## Common patterns
-### Fast Dependencies + Slow Build
+### Fast dependencies + slow build
Install dependencies blocking (must complete before work), build in background:
@@ -354,7 +354,7 @@ post-create = "npm install"
post-start = "npm run build"
```
-### Progressive Validation
+### Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -368,7 +368,7 @@ test = "npm test"
build = "npm run build"
```
-### Target-Specific Behavior
+### Target-specific behavior
Different behavior based on merge target:
@@ -382,7 +382,7 @@ fi
"""
```
-### Symlinks and Caches
+### Symlinks and caches
Set up shared resources that shouldn't be duplicated:
diff --git a/docs/content/list.md b/docs/content/list.md
index f46d18555..722ba69cd 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -99,7 +99,7 @@ The CI column shows GitHub/GitLab pipeline status:
Any CI dot appears dimmed when there are unpushed local changes (stale status).
-## Status Symbols
+## Status symbols
Symbols appear in the Status column in this order:
@@ -126,7 +126,7 @@ Symbols appear in the Status column in this order:
Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-## JSON Output
+## JSON output
Query structured data with `--format=json`:
@@ -156,13 +156,13 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
- `is_current` — Current directory
- `is_previous` — Previous worktree from [wt switch](@/switch.md)
-## See Also
+## See also
- [wt select](@/select.md) — Interactive worktree picker with live preview
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->
diff --git a/docs/content/merge.md b/docs/content/merge.md
index b622de4bc..3b37cf63f 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -58,7 +58,7 @@ wt merge --no-commit
Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
-## See Also
+## See also
- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
- [wt remove](@/remove.md) — Remove worktrees without merging
@@ -66,7 +66,7 @@ Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clea
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
diff --git a/docs/content/remove.md b/docs/content/remove.md
index fba963cf0..40bf3380f 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -37,26 +37,26 @@ Force-delete an unmerged branch:
wt remove -D experimental
```
-## Branch Cleanup
+## Branch cleanup
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
-## Background Removal
+## Background removal
Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
Arguments resolve by path first, then branch name—see [wt switch](@/switch.md#path-first-lookup). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).
-## See Also
+## See also
- [wt merge](@/merge.md) — Remove worktree after merging
- [wt list](@/list.md) — View all worktrees
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit cli.rs to update -->
diff --git a/docs/content/select.md b/docs/content/select.md
index 5d7466238..4bd94cba1 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -18,7 +18,7 @@ Open the selector:
wt select
```
-## Preview Tabs
+## Preview tabs
Toggle between views with number keys:
@@ -38,14 +38,14 @@ Toggle between views with number keys:
| `Alt+p` | Toggle preview panel |
| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
-## See Also
+## See also
- [wt list](@/list.md) — Static table view with all worktree metadata
- [wt switch](@/switch.md) — Direct switching when you know the target branch
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->
diff --git a/docs/content/step.md b/docs/content/step.md
index c782070fd..da449d636 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -51,13 +51,13 @@ wt step push
- `pre-merge` — Before pushing to target
- `post-merge` — After merge cleanup
-## See Also
+## See also
- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->
diff --git a/docs/content/switch.md b/docs/content/switch.md
index d72a57216..fadfee168 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -24,7 +24,7 @@ wt switch --create hotfix --base production
For interactive selection, use [`wt select`](@/select.md).
-## Creating Worktrees
+## Creating worktrees
With `--create`, worktrunk:
@@ -55,7 +55,7 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
-## Path-First Lookup
+## Path-first lookup
Arguments resolve by checking the filesystem before git branches:
@@ -67,7 +67,7 @@ Arguments resolve by checking the filesystem before git branches:
- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)
- `wt switch bar` → also works (branch lookup finds same worktree)
-## See Also
+## See also
- [wt select](@/select.md) — Interactive worktree selection
- [wt list](@/list.md) — View all worktrees
@@ -76,7 +76,7 @@ Arguments resolve by checking the filesystem before git branches:
---
-## Command Reference
+## Command reference
<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
diff --git a/src/cli.rs b/src/cli.rs
index ce0b83c98..9f464f8e6 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -160,7 +160,7 @@ Zsh (~/.zshrc):
eval "$(wt config shell init zsh)"
```
-## Auto Setup
+## Auto setup
Use `wt config shell install` to add to the shell config automatically."#)]
Init {
@@ -170,7 +170,7 @@ Use `wt config shell install` to add to the shell config automatically."#)]
},
/// Write shell integration to config files
- #[command(after_long_help = r#"## Auto Setup
+ #[command(after_long_help = r#"## Auto setup
Detects existing shell config files and adds integration:
```console
@@ -212,7 +212,7 @@ Skip confirmation prompt:
wt config shell uninstall --force
```
-## Version Tolerance
+## Version tolerance
Detects various forms of the integration pattern regardless of:
- Command prefix (wt, worktree, etc.)
@@ -286,7 +286,7 @@ and project config (`.config/wt.toml`).
If a config file doesn't exist, shows defaults that would be used.
-## Doctor Mode
+## Doctor mode
Use `--doctor` to test commit generation with a synthetic diff:
@@ -314,7 +314,7 @@ commit messages."#
after_long_help = r#"Variables are runtime values stored in git config, separate from
configuration files. Use `wt config show` to view file-based configuration.
-## Available Variables
+## Available variables
- **default-branch**: The repository's default branch (read-only, cached)
- **marker**: Custom status marker for a branch (shown in `wt list`)
@@ -676,7 +676,7 @@ Show current configuration and file locations:
wt config show
```
-## Shell Integration
+## Shell integration
Shell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.
@@ -693,7 +693,7 @@ eval "$(wt config shell init zsh)"
wt config shell init fish | source
```
-## Configuration Files
+## Configuration files
**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):
@@ -703,7 +703,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.
-## LLM Commit Messages
+## LLM commit messages
Worktrunk can generate commit messages using an LLM. Enable in user config:
@@ -766,7 +766,7 @@ wt step push
- `pre-merge` — Before pushing to target
- `post-merge` — After merge cleanup
-## See Also
+## See also
- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
"#
@@ -791,7 +791,7 @@ Open the selector:
wt select
```
-## Preview Tabs
+## Preview tabs
Toggle between views with number keys:
@@ -811,7 +811,7 @@ Toggle between views with number keys:
| `Alt+p` | Toggle preview panel |
| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
-## See Also
+## See also
- [wt list](@/list.md) — Static table view with all worktree metadata
- [wt switch](@/switch.md) — Direct switching when you know the target branch
@@ -883,7 +883,7 @@ The CI column shows GitHub/GitLab pipeline status:
Any CI dot appears dimmed when there are unpushed local changes (stale status).
-## Status Symbols
+## Status symbols
Symbols appear in the Status column in this order:
@@ -910,7 +910,7 @@ Symbols appear in the Status column in this order:
Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-## JSON Output
+## JSON output
Query structured data with `--format=json`:
@@ -940,7 +940,7 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
- `is_current` — Current directory
- `is_previous` — Previous worktree from [wt switch](@/switch.md)
-## See Also
+## See also
- [wt select](@/select.md) — Interactive worktree picker with live preview
"#
@@ -995,7 +995,7 @@ wt switch --create hotfix --base production
For interactive selection, use [`wt select`](@/select.md).
-## Creating Worktrees
+## Creating worktrees
With `--create`, worktrunk:
@@ -1026,7 +1026,7 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
-## Path-First Lookup
+## Path-first lookup
Arguments resolve by checking the filesystem before git branches:
@@ -1038,7 +1038,7 @@ Arguments resolve by checking the filesystem before git branches:
- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)
- `wt switch bar` → also works (branch lookup finds same worktree)
-## See Also
+## See also
- [wt select](@/select.md) — Interactive worktree selection
- [wt list](@/list.md) — View all worktrees
@@ -1106,19 +1106,19 @@ Force-delete an unmerged branch:
wt remove -D experimental
```
-## Branch Cleanup
+## Branch cleanup
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
-## Background Removal
+## Background removal
Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
Arguments resolve by path first, then branch name—see [wt switch](@/switch.md#path-first-lookup). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).
-## See Also
+## See also
- [wt merge](@/merge.md) — Remove worktree after merging
- [wt list](@/list.md) — View all worktrees
@@ -1194,7 +1194,7 @@ wt merge --no-commit
Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
-## See Also
+## See also
- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
- [wt remove](@/remove.md) — Remove worktrees without merging
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index 3a9051bc3..749ace275 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -103,10 +103,10 @@ Each command page should follow this order:
1. **Intro paragraph** — One or two sentences: what the command does and when to use it. Integrate key behavioral distinctions (e.g., "Switching to an existing worktree is just a directory change. With `--create`, hooks run.")
2. **Examples** — Common use cases with brief labels, immediately after intro
-3. **Feature sections** — Deeper explanation of major features (e.g., "Creating Worktrees", "Shortcuts")
+3. **Feature sections** — Deeper explanation of major features (e.g., "Creating worktrees", "Shortcuts")
4. **Hooks** — Brief summary with link to `/hooks/` for details
5. **Technical details** — Implementation details like argument resolution, pushed to the bottom
-6. **Command Reference** — Auto-generated from `--help-page`, always last
+6. **Command reference** — Auto-generated from `--help-page`, always last
### Writing Style
diff --git a/src/main.rs b/src/main.rs
index fb1299076..fc49579cb 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -146,7 +146,7 @@ fn maybe_handle_help_with_pager() -> bool {
///
/// ---
///
-/// ## Command Reference
+/// ## Command reference
///
/// ```bash
/// wt merge — ...
@@ -270,7 +270,7 @@ fn handle_help_page(args: &[String]) {
println!();
println!("---");
println!();
- println!("## Command Reference");
+ println!("## Command reference");
println!();
println!(
"<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"
diff --git a/tests/common/progressive_output.rs b/tests/common/progressive_output.rs
index 0bb17382b..8b608586f 100644
--- a/tests/common/progressive_output.rs
+++ b/tests/common/progressive_output.rs
@@ -117,8 +117,8 @@ const STABLE_READ_THRESHOLD: u32 = 4;
/// On slow CI systems (especially Ubuntu), the PTY may return spurious EOFs before
/// all data has been flushed from the kernel buffer. This ensures we wait long enough
/// for the kernel to complete its PTY buffer flush, regardless of how many EOFs we've seen.
-/// 500ms provides enough margin for slow CI runners under load.
-const MIN_DRAIN_WAIT_MS: u64 = 500;
+/// 1000ms provides enough margin for slow CI runners under load with many worktrees.
+const MIN_DRAIN_WAIT_MS: u64 = 1000;
/// Strategy for capturing progressive output snapshots
#[derive(Debug, Clone)]
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 5d7843401..2800d846f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -58,7 +58,7 @@ Show current configuration and file locations:
wt config show
-Shell Integration
+Shell integration
Shell integration allows Worktrunk to change the shell's working directory after wt switch. Without it, commands run in a subprocess and directory changes don't persist.
@@ -73,7 +73,7 @@ The wt config shell install command adds integration to the shell's conf
# For fish: add to ~/.config/fish/config.fish
wt config shell init fish | source
-Configuration Files
+Configuration files
User config — ~/.config/worktrunk/config.toml (or $WORKTRUNK_CONFIG_PATH):
@@ -83,7 +83,7 @@ Personal settings like LLM commit generation, path templates, and default behavi
Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See Hooks for details.
-LLM Commit Messages
+LLM commit messages
Worktrunk can generate commit messages using an LLM. Enable in user config:
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_show.snap b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
index 1fc7f3a77..a0b58da41 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_show.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
@@ -43,7 +43,7 @@ and project config (.config/wt.toml).
If a config file doesn't exist, shows defaults that would be used.
-Doctor Mode
+Doctor mode
Use --doctor to test commit generation with a synthetic diff:
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_var.snap b/tests/snapshots/integration__integration_tests__help__help_config_var.snap
index c69cf1c77..8dadaf9c4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_var.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_var.snap
@@ -43,7 +43,7 @@ Usage: wt config var [OPTIONS] <COMMAND>
Variables are runtime values stored in git config, separate from
configuration files. Use wt config show to view file-based configuration.
-Available Variables
+Available variables
- default-branch: The repository's default branch (read-only, cached)
- marker: Custom status marker for a branch (shown in wt list)
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 07228cfe1..c302fa007 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -108,7 +108,7 @@ The CI column shows GitHub/GitLab pipeline status:
Any CI dot appears dimmed when there are unpushed local changes (stale status).
-Status Symbols
+Status symbols
Symbols appear in the Status column in this order:
@@ -135,7 +135,7 @@ Symbols appear in the Status column in this order:
Rows are dimmed when the branch has no marginal contribution (≡ matches main or _ no commits).
-JSON Output
+JSON output
Query structured data with --format=json:
@@ -163,6 +163,6 @@ Query structured data with --format=json:
- is_current — Current directory
- is_previous — Previous worktree from wt switch
-See Also
+See also
- wt select — Interactive worktree picker with live preview
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 a63697f82..b02dbf9e3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -105,7 +105,7 @@ Skip git operations, only run hooks and push:
Use --no-commit to skip steps 1-3 and only run hooks and push. Requires a clean working tree and --no-remove.
-See Also
+See also
- wt step — Run individual merge steps (commit, squash, rebase, push)
- wt remove — Remove worktrees without merging
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index db31576a6..9f26bed17 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -68,19 +68,19 @@ Force-delete an unmerged branch:
wt remove -D experimental
-Branch Cleanup
+Branch cleanup
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
Use -D to force-delete unmerged branches. Use --no-delete-branch to keep the branch.
-Background Removal
+Background removal
Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --no-background to run in the foreground.
Arguments resolve by path first, then branch name—see wt switch. Shortcuts: @ (current), - (previous), ^ (main worktree).
-See Also
+See also
- wt merge — Remove worktree after merging
- wt list — View all worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 5b796018f..96cd3a990 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -82,6 +82,6 @@ Manual merge workflow with review between steps:
- pre-merge — Before pushing to target
- post-merge — After merge cleanup
-See Also
+See also
- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
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 7179e071a..37fa2dc94 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -71,7 +71,7 @@ Two distinct operations:
For interactive selection, use `wt select`.
-Creating Worktrees
+Creating worktrees
With --create, worktrunk:
@@ -98,7 +98,7 @@ With --create, worktrunk:
wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
-Path-First Lookup
+Path-first lookup
Arguments resolve by checking the filesystem before git branches:
@@ -110,7 +110,7 @@ Arguments resolve by checking the filesystem before git branches:
- wt switch foo → switches to repo.foo/ (the bar worktree)
- wt switch bar → also works (branch lookup finds same worktree)
-See Also
+See also
- wt select — Interactive worktree selection
- wt list — View all worktrees