Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Update command page generation to use skeleton files with marker regions
Maximilian Roosedbf068d1e12
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex e9140a2b9..4fac6a769 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -84,20 +84,39 @@ When adding new positioned elements:## 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.+Command pages (e.g., `switch.md`, `merge.md`, `list.md`) are **generated from the CLI source code**. Each file has a **skeleton** (frontmatter) with a marker region that gets replaced by generated content.### Generation mechanism-Each command page is generated by running:+Each command page has this structure:++```markdown+++++title = "wt list"+weight = 11++[extra]+group = "Commands"++++++<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->++[generated content here]++<!-- END AUTO-GENERATED from `wt list --help-page` -->+```++The END tag mirrors the source ID, enabling precise matching even with nested snapshot markers inside.++The frontmatter (title, weight, group) is preserved in each file. Everything between the START and END markers is generated by:```bash-wt <command> --help-page > docs/content/<command>.md+wt <command> --help-page```-The output combines:-1. **Zola frontmatter** — title, weight, group metadata-2. **Conceptual documentation** — from `after_long_help` in `src/cli.rs`-3. **Command Reference section** — the standard `--help` output+The generated content includes:+1. **Conceptual documentation** — from `after_long_help` in `src/cli.rs`+2. **Command Reference section** — the standard `--help` output### Editing command docs@@ -181,11 +200,20 @@ To add web-only styling for new content, edit `colorize_ci_status_for_html()` inSimilarly, `md_help::colorize_status_symbols()` applies ANSI colors for terminal `--help` output.-The generated files contain this warning comment in the Command Reference section:+All AUTO-GENERATED markers use a consistent format with START and END tags:+```html+<!-- ⚠️ AUTO-GENERATED from <source> — edit <file> to update -->+[content]+<!-- END AUTO-GENERATED -->+```++For regions that may contain nested markers (like command pages with embedded snapshots), the END tag mirrors the source ID:```html-<!-- ⚠️ AUTO-GENERATED from `wt <command> --help-page` — edit cli.rs to update -->+<!-- END AUTO-GENERATED from `wt list --help-page` -->```+This enables precise matching of the outer region.+## Demo GIF workflowDemo GIFs (~2MB each) are stored in a separate `worktrunk-assets` repo to avoid bloating git history.diff --git a/docs/content/config.md b/docs/content/config.mdindex edf8342d0..aab8537ca 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -6,7 +6,7 @@ weight = 15group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit cli.rs to update -->Manages configuration, shell integration, and runtime settings.@@ -217,8 +217,6 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit cli.rs to update -->-```wt config - Manage configuration and shell integrationUsage: wt config [OPTIONS] <COMMAND>@@ -245,3 +243,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt config --help-page` -->diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 824f8cee7..9260315fd 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -6,7 +6,7 @@ weight = 17group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt hook --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt hook --help-page` — edit cli.rs to update -->Run project-defined lifecycle hooks from `.config/wt.toml`.@@ -295,8 +295,6 @@ env = "cp {{ repo_root }}/.env.local .env"## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt hook --help-page` — edit cli.rs to update -->-```wt hook - Run project hooksUsage: wt hook [OPTIONS] <COMMAND>@@ -323,3 +321,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt hook --help-page` -->diff --git a/docs/content/list.md b/docs/content/list.mdindex 5c2503627..4fbc5ef42 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -6,7 +6,7 @@ weight = 11group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.@@ -181,8 +181,6 @@ wt list --format=json | jq '.[] | select(.branch_state == "integrated" or .branc## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->-```wt list - List worktrees and optionally branchesUsage: wt list [OPTIONS]@@ -224,3 +222,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt list --help-page` -->diff --git a/docs/content/merge.md b/docs/content/merge.mdindex 30c91011a..afa0422ae 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -6,7 +6,7 @@ weight = 13group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->Merge the current branch into the target branch and clean up. Handles the full workflow: commit uncommitted changes, squash commits, rebase, run hooks, push to target, and remove the worktree.@@ -68,8 +68,6 @@ Use `--no-commit` to skip all git operations (steps 1-2) and only run hooks and## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->-```wt merge - Merge worktree into target branchUsage: wt merge [OPTIONS] [TARGET]@@ -117,3 +115,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt merge --help-page` -->diff --git a/docs/content/remove.md b/docs/content/remove.mdindex 21934e8da..ff4e34b5b 100644--- a/docs/content/remove.md+++ b/docs/content/remove.md@@ -6,7 +6,7 @@ weight = 12group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit cli.rs to update -->Removes worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.@@ -67,8 +67,6 @@ Arguments resolve by path first, then branch name. [Shortcuts](@/switch.md#short## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit cli.rs to update -->-```wt remove - Remove worktree and branchUsage: wt remove [OPTIONS] [WORKTREES]...@@ -103,3 +101,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt remove --help-page` -->diff --git a/docs/content/select.md b/docs/content/select.mdindex 9060d4df2..327fdefbd 100644--- a/docs/content/select.md+++ b/docs/content/select.md@@ -6,7 +6,7 @@ weight = 14group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.@@ -51,8 +51,6 @@ Toggle between views with number keys:## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->-```wt select - Interactive worktree selector@@ -73,3 +71,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt select --help-page` -->diff --git a/docs/content/step.md b/docs/content/step.mdindex fd42c0d3a..b5597b72c 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -6,7 +6,7 @@ weight = 16group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->Run individual git workflow operations: commits, squashes, rebases, and pushes.@@ -44,8 +44,6 @@ wt step push## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->-```wt step - Run individual workflow operationsUsage: wt step [OPTIONS] <COMMAND>@@ -70,3 +68,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt step --help-page` -->diff --git a/docs/content/switch.md b/docs/content/switch.mdindex b5d50a58d..93d4f41fe 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -6,7 +6,7 @@ weight = 10group = "Commands"+++-<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit src/cli.rs to update -->+<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->Two distinct operations:@@ -66,8 +66,6 @@ wt switch --create fix --base=@ # Branch from current HEAD## Command reference-<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->-```wt switch - Switch to a worktreeUsage: wt switch [OPTIONS] <BRANCH>@@ -117,3 +115,5 @@ Global Options:-v, --verboseShow commands and debug info```++<!-- END AUTO-GENERATED from `wt switch --help-page` -->diff --git a/src/main.rs b/src/main.rsindex 11bd1f834..778a17851 100644--- a/src/main.rs+++ b/src/main.rs@@ -241,35 +241,11 @@ fn handle_help_page(args: &[String]) {help_block};- // Title uses "wt <command>" format for consistency- let title = format!("wt {subcommand}");-- // Weight mapping (for nav order)- // Commands are grouped together after Concepts (weight 3)- // Order: switch, list (daily use), remove, merge (workflow completion), then utilities- let weight = match subcommand.as_str() {- "switch" => 10,- "list" => 11,- "remove" => 12,- "merge" => 13,- "select" => 14,- "config" => 15,- "step" => 16,- "hook" => 17,- other => panic!("Unknown command '{other}' needs a weight assignment"),- };-- // Output the page- println!("+++");- println!("title = \"{title}\"");- println!("weight = {weight}");- println!();- println!("[extra]");- println!("group = \"Commands\"");- println!("+++");- println!();+ // Output the generated content (frontmatter is in skeleton files)+ // Uses region markers so sync can replace just this content+ // END tag mirrors the ID for unambiguous matching with nested markersprintln!(- "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit src/cli.rs to update -->"+ "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->");println!();println!("{}", after_help.trim());@@ -278,14 +254,12 @@ fn handle_help_page(args: &[String]) {println!();println!("## Command reference");println!();- println!(- "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"- );- println!();println!("```");print!("{}", reference_block.trim());println!();println!("```");+ println!();+ println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");}/// Add HTML color spans for CI status dots in help page output.diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex b0746b8df..03b047093 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1048,6 +1048,7 @@ fn test_docs_quickstart_examples_are_in_sync() {}/// Command pages generated via `wt <cmd> --help-page`+/// Each page preserves its frontmatter and replaces the AUTO-GENERATED marker region.const COMMAND_PAGES: &[&str] = &["switch", "list", "merge", "remove", "select", "config", "step", "hook",];@@ -1065,7 +1066,7 @@ fn test_command_pages_are_in_sync() {continue;}- // Run wt <cmd> --help-page+ // Run wt <cmd> --help-page (outputs START marker + content + END marker)let output = Command::new(env!("CARGO_BIN_EXE_wt")).args([cmd, "--help-page"]).current_dir(project_root)@@ -1083,13 +1084,12 @@ fn test_command_pages_are_in_sync() {}// Strip trailing whitespace from each line (pre-commit does this)- let expected: String = String::from_utf8_lossy(&output.stdout)+ let generated: String = String::from_utf8_lossy(&output.stdout).lines().map(|line| line.trim_end()).collect::<Vec<_>>()- .join("\n")- + "\n"; // Ensure trailing newline- if expected.trim().is_empty() {+ .join("\n");+ if generated.trim().is_empty() {errors.push(format!("Empty output from 'wt {} --help-page': {}",cmd,@@ -1100,7 +1100,7 @@ fn test_command_pages_are_in_sync() {// Expand command placeholders ($ wt list -> terminal shortcode with snapshot output)let snapshots_dir = project_root.join("tests/snapshots");- let expected = match expand_command_placeholders(&expected, &snapshots_dir) {+ let generated = match expand_command_placeholders(&generated, &snapshots_dir) {Ok(expanded) => expanded,Err(e) => {errors.push(format!(@@ -1114,8 +1114,29 @@ fn test_command_pages_are_in_sync() {let current = fs::read_to_string(&doc_path).unwrap_or_else(|e| panic!("Failed to read {}: {}", doc_path.display(), e));- if current != expected {- fs::write(&doc_path, &expected)+ // Find the help-page marker region using mirrored END tag+ // Pattern: <!-- ⚠️ AUTO-GENERATED from `wt cmd --help-page` ... --> ... <!-- END AUTO-GENERATED from `wt cmd --help-page` -->+ let marker_pattern = Regex::new(&format!(+ r"(?s)<!-- ⚠️ AUTO-GENERATED from `wt {} --help-page`[^>]*-->.*?<!-- END AUTO-GENERATED from `wt {} --help-page` -->",+ cmd, cmd+ )).unwrap();++ let new_content = if let Some(m) = marker_pattern.find(¤t) {+ let before = ¤t[..m.start()];+ let after = ¤t[m.end()..];+ format!("{}{}{}", before, generated.trim(), after)+ } else {+ errors.push(format!(+ "No AUTO-GENERATED region found in {}. \+ Ensure file has marker region for `wt {} --help-page`.",+ doc_path.display(),+ cmd+ ));+ continue;+ };++ if current != new_content {+ fs::write(&doc_path, &new_content).unwrap_or_else(|e| panic!("Failed to write {}: {}", doc_path.display(), e));updated += 1;}