Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Adjust help output heading levels
Maximilian Roosa1f09cf5c0f5
diff --git a/README.md b/README.mdindex bbb7830ce..be892a393 100644--- a/README.md+++ b/README.md@@ -505,9 +505,9 @@ Global Options:```-## Operation+### Operation-### Worktree resolution+#### Worktree resolutionArguments are resolved using **path-first lookup**:@@ -520,13 +520,13 @@ Arguments are resolved using **path-first lookup**:- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)- `wt switch bar` also works (falls back to branch lookup)-### Switching to Existing Worktree+#### Switching to Existing Worktree- If worktree exists at expected path or for branch, changes directory via shell integration- No hooks run- No branch creation-### Creating New Worktree (`--create`)+#### Creating New Worktree (`--create`)1. Creates new branch (defaults to current default branch as base)2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)@@ -535,16 +535,16 @@ Arguments are resolved using **path-first lookup**:5. Spawns post-start hooks in background (non-blocking)6. Changes directory to new worktree via shell integration-## Hooks+### Hooks-### post-create (sequential, blocking)+#### post-create (sequential, blocking)- Run after worktree creation, before success message- Typically: `npm install`, `cargo build`, setup tasks- Failures block the operation- Skip with `--no-verify`-### post-start (parallel, background)+#### post-start (parallel, background)- Spawned after success message shown- Typically: dev servers, file watchers, editors@@ -558,7 +558,7 @@ Arguments are resolved using **path-first lookup**:Approvals are saved to user config. Use `--force` to bypass prompts.See `wt config approvals --help`.-## Examples+### ExamplesSwitch to existing worktree:@@ -596,7 +596,7 @@ Skip hooks during creation:wt switch --create temp --no-verify```-## Shortcuts+### ShortcutsUse `@` for current HEAD, `-` for previous, `^` for main:@@ -666,34 +666,34 @@ Global Options:```-## Operation+### OperationCommit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks-### Commit+#### CommitUncommitted changes are staged and committed with LLM commit message.Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.-### Squash+#### SquashMultiple commits are squashed into one (like GitHub's "Squash and merge") with LLM commit message.Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`-### Rebase+#### RebaseBranch is rebased onto target. Conflicts abort the merge immediately.-### Hooks+#### HooksPre-merge commands run after rebase (failures abort). Post-merge commandsrun after cleanup (failures logged). Skip all with `--no-verify`.-### Push+#### PushFast-forward push to local target branch. Non-fast-forward pushes are rejected.-### Cleanup+#### CleanupWorktree and branch are removed. Skip with `--no-remove`.@@ -703,7 +703,7 @@ Worktree and branch are removed. Skip with `--no-remove`.Approvals are saved to user config. Use `--force` to bypass prompts.See `wt config approvals --help`.-## Examples+### ExamplesBasic merge to main:@@ -771,21 +771,21 @@ Global Options:```-## Operation+### OperationRemoves worktree directory, git metadata, and branch. Requires clean working tree.-### No arguments (remove current)+#### No arguments (remove current)- Removes current worktree and switches to main worktree- In main worktree: switches to default branch-### By name (remove specific)+#### By name (remove specific)- Removes specified worktree(s) and branches- Current worktree removed last (switches to main first)-### Worktree resolution+#### Worktree resolutionArguments are resolved to worktrees using **path-first lookup**:@@ -807,7 +807,7 @@ branch `foo` has a different worktree at `repo.bar/`, an error is raised.- `-` - previous worktree (from switch history)- `^` - main worktree-### Branch deletion+#### Branch deletionBy default, branches are deleted only when their content is already in the target branch:@@ -820,17 +820,17 @@ This handles workflows where PRs are squash-merged or rebased, which don't presecommit ancestry but do integrate the content. Use `-D` to delete unintegratedbranches, or `--no-delete-branch` to always keep branches.-### Background removal (default)+#### Background removal (default)- Returns immediately for continued work- Logs: `.git/wt-logs/{branch}-remove.log`- Use `--no-background` for foreground (blocking)-### Cleanup+#### CleanupStops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.-## Examples+### ExamplesRemove current worktree and branch:@@ -920,7 +920,7 @@ Global Options:```-## Columns+### Columns- **Branch:** Branch name- **Status:** Quick status symbols (see Status Symbols below)@@ -941,7 +941,7 @@ Global Options:- **Age:** Time since last commit (relative)- **Message:** Last commit message (truncated)-## Status Symbols+### Status SymbolsOrder: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`@@ -966,7 +966,7 @@ Order: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`Rows are dimmed when there's no marginal contribution (`≡` matches main OR `_` no commits).-## JSON Output+### JSON OutputUse `--format=json` for structured data. Each object contains two status mapswith the same fields in the same order as Status Symbols above:@@ -1049,7 +1049,7 @@ Global Options:```-## Setup Guide+### Setup Guide1. Set up shell integration@@ -1082,7 +1082,7 @@ Global Options:command = "llm"```-## LLM Setup Details+### LLM Setup DetailsFor Claude:@@ -1101,7 +1101,7 @@ llm keys set openaiUse `wt config show` to view the current configuration.Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>-## Configuration Files+### Configuration Files**User config**:diff --git a/docs/content/commands.md b/docs/content/commands.mdindex b4f2a54bf..8e6dabb11 100644--- a/docs/content/commands.md+++ b/docs/content/commands.md@@ -50,9 +50,9 @@ Global Options:```-## Operation+### Operation-### Worktree resolution+#### Worktree resolutionArguments are resolved using **path-first lookup**:@@ -65,13 +65,13 @@ Arguments are resolved using **path-first lookup**:- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)- `wt switch bar` also works (falls back to branch lookup)-### Switching to Existing Worktree+#### Switching to Existing Worktree- If worktree exists at expected path or for branch, changes directory via shell integration- No hooks run- No branch creation-### Creating New Worktree (`--create`)+#### Creating New Worktree (`--create`)1. Creates new branch (defaults to current default branch as base)2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)@@ -80,16 +80,16 @@ Arguments are resolved using **path-first lookup**:5. Spawns post-start hooks in background (non-blocking)6. Changes directory to new worktree via shell integration-## Hooks+### Hooks-### post-create (sequential, blocking)+#### post-create (sequential, blocking)- Run after worktree creation, before success message- Typically: `npm install`, `cargo build`, setup tasks- Failures block the operation- Skip with `--no-verify`-### post-start (parallel, background)+#### post-start (parallel, background)- Spawned after success message shown- Typically: dev servers, file watchers, editors@@ -103,7 +103,7 @@ Arguments are resolved using **path-first lookup**:Approvals are saved to user config. Use `--force` to bypass prompts.See `wt config approvals --help`.-## Examples+### ExamplesSwitch to existing worktree:@@ -141,7 +141,7 @@ Skip hooks during creation:wt switch --create temp --no-verify```-## Shortcuts+### ShortcutsUse `@` for current HEAD, `-` for previous, `^` for main:@@ -210,34 +210,34 @@ Global Options:```-## Operation+### OperationCommit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks-### Commit+#### CommitUncommitted changes are staged and committed with LLM commit message.Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.-### Squash+#### SquashMultiple commits are squashed into one (like GitHub's "Squash and merge") with LLM commit message.Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`-### Rebase+#### RebaseBranch is rebased onto target. Conflicts abort the merge immediately.-### Hooks+#### HooksPre-merge commands run after rebase (failures abort). Post-merge commandsrun after cleanup (failures logged). Skip all with `--no-verify`.-### Push+#### PushFast-forward push to local target branch. Non-fast-forward pushes are rejected.-### Cleanup+#### CleanupWorktree and branch are removed. Skip with `--no-remove`.@@ -247,7 +247,7 @@ Worktree and branch are removed. Skip with `--no-remove`.Approvals are saved to user config. Use `--force` to bypass prompts.See `wt config approvals --help`.-## Examples+### ExamplesBasic merge to main:@@ -314,21 +314,21 @@ Global Options:```-## Operation+### OperationRemoves worktree directory, git metadata, and branch. Requires clean working tree.-### No arguments (remove current)+#### No arguments (remove current)- Removes current worktree and switches to main worktree- In main worktree: switches to default branch-### By name (remove specific)+#### By name (remove specific)- Removes specified worktree(s) and branches- Current worktree removed last (switches to main first)-### Worktree resolution+#### Worktree resolutionArguments are resolved to worktrees using **path-first lookup**:@@ -350,7 +350,7 @@ branch `foo` has a different worktree at `repo.bar/`, an error is raised.- `-` - previous worktree (from switch history)- `^` - main worktree-### Branch deletion+#### Branch deletionBy default, branches are deleted only when their content is already in the target branch:@@ -363,17 +363,17 @@ This handles workflows where PRs are squash-merged or rebased, which don't presecommit ancestry but do integrate the content. Use `-D` to delete unintegratedbranches, or `--no-delete-branch` to always keep branches.-### Background removal (default)+#### Background removal (default)- Returns immediately for continued work- Logs: `.git/wt-logs/{branch}-remove.log`- Use `--no-background` for foreground (blocking)-### Cleanup+#### CleanupStops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.-## Examples+### ExamplesRemove current worktree and branch:@@ -462,7 +462,7 @@ Global Options:```-## Columns+### Columns- **Branch:** Branch name- **Status:** Quick status symbols (see Status Symbols below)@@ -483,7 +483,7 @@ Global Options:- **Age:** Time since last commit (relative)- **Message:** Last commit message (truncated)-## Status Symbols+### Status SymbolsOrder: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`@@ -508,7 +508,7 @@ Order: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`Rows are dimmed when there's no marginal contribution (`≡` matches main OR `_` no commits).-## JSON Output+### JSON OutputUse `--format=json` for structured data. Each object contains two status mapswith the same fields in the same order as Status Symbols above:@@ -590,7 +590,7 @@ Global Options:```-## Setup Guide+### Setup Guide1. Set up shell integration@@ -623,7 +623,7 @@ Global Options:command = "llm"```-## LLM Setup Details+### LLM Setup DetailsFor Claude:@@ -642,7 +642,7 @@ llm keys set openaiUse `wt config show` to view the current configuration.Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>-## Configuration Files+### Configuration Files**User config**:diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex ea04fa314..fbed7b44f 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -393,6 +393,8 @@ fn get_help_output(command: &str, project_root: &Path) -> Result<String, String>// Format for README display:// 1. Replace " - " with em dash in first line (command description)// 2. Split at first ## header - synopsis in code block, rest as markdown+ // 3. Increase heading levels in docs section (## -> ###, ### -> ####)+ // so they become children of the command heading (which is ##)let result = if let Some(first_newline) = help_output.find('\n') {let (first_line, rest) = help_output.split_at(first_newline);// Replace hyphen-minus with em dash in command description@@ -402,6 +404,8 @@ fn get_help_output(command: &str, project_root: &Path) -> Result<String, String>// Split at first H2 headerlet (synopsis, docs) = rest.split_at(header_pos);let docs = docs.trim_start_matches('\n');+ // Increase heading levels so docs headings become children of command heading+ let docs = increase_heading_levels(docs);format!("```text\n{}{}\n```\n\n{}", first_line, synopsis, docs)} else {// No documentation section, wrap everything in code block@@ -415,6 +419,32 @@ fn get_help_output(command: &str, project_root: &Path) -> Result<String, String>Ok(result)}+/// Increase markdown heading levels by one (## -> ###, ### -> ####, etc.)+/// This makes help output headings children of the command heading in docs.+/// Only transforms actual markdown headings, not code block content.+fn increase_heading_levels(content: &str) -> String {+ let mut result = Vec::new();+ let mut in_code_block = false;++ for line in content.lines() {+ // Track code block boundaries (``` or ````+)+ if line.trim_start().starts_with("```") {+ in_code_block = !in_code_block;+ result.push(line.to_string());+ continue;+ }++ // Only transform headings outside code blocks+ if !in_code_block && line.starts_with('#') {+ result.push(format!("#{}", line));+ } else {+ result.push(line.to_string());+ }+ }++ result.join("\n")+}+/// Update a section in the README content, returning (new content, updated count, total count)/// The replacement function receives (id, current_content) to allow preserving existing values.fn update_readme_section(