Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Refactor README code blocks and CLI examples
Maximilian Roos808813ed1091
diff --git a/README.md b/README.mdindex b3f3af26d..87b7dfbaa 100644--- a/README.md+++ b/README.md@@ -303,7 +303,7 @@ instead of duplicating logic:<!-- README:help:wt switch --help-md -->```-wt switch - Switch to a worktree+wt switch — Switch to a worktreeUsage: switch [OPTIONS] <BRANCH>Arguments:@@ -331,6 +331,7 @@ Options:-h, --helpPrint help (see a summary with '-h')+```## Operation### Switching to Existing Worktree@@ -420,7 +421,7 @@ wt remove @ # Remove current worktree<!-- README:help:wt merge --help-md -->```-wt merge - Merge worktree into target branch+wt merge — Merge worktree into target branchUsage: merge [OPTIONS] [TARGET]Arguments:@@ -456,6 +457,7 @@ Options:-h, --helpPrint help (see a summary with '-h')+```## OperationCommit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks@@ -514,7 +516,6 @@ Skip all hooks:```bashwt merge --no-verify```-```<!-- README:end --></details>@@ -524,7 +525,7 @@ wt merge --no-verify<!-- README:help:wt remove --help-md -->```-wt remove - Remove worktree and branch+wt remove — Remove worktree and branchUsage: remove [OPTIONS] [WORKTREES]...Arguments:@@ -544,6 +545,7 @@ Options:-h, --helpPrint help (see a summary with '-h')+```## OperationRemoves worktree directory, git metadata, and branch. Requires clean working tree.@@ -599,7 +601,6 @@ Switch to default in main:```bashwt remove # (when already in main worktree)```-```<!-- README:end --></details>@@ -609,7 +610,7 @@ wt remove # (when already in main worktree)<!-- README:help:wt list --help-md -->```-wt list - List worktrees and optionally branches+wt list — List worktrees and optionally branchesUsage: list [OPTIONS]Options:@@ -635,6 +636,7 @@ Options:-h, --helpPrint help (see a summary with '-h')+```## Columns- **Branch:** Branch name@@ -718,7 +720,6 @@ jq '.[] | select(.status.main_divergence == "Ahead")'# Find locked worktreesjq '.[] | select(.locked != null)'```-```<!-- README:end --></details>@@ -728,7 +729,7 @@ jq '.[] | select(.locked != null)'<!-- README:help:wt config --help-md -->```-wt config - Manage configuration and shell integration+wt config — Manage configuration and shell integrationUsage: config <COMMAND>Commands:@@ -744,6 +745,7 @@ Options:-h, --helpPrint help (see a summary with '-h')+```## Setup Guide1. Set up shell integration@@ -799,7 +801,6 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat**Project config** (repository hooks):- Location: `.config/wt.toml` in repository root- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks-```<!-- README:end --></details>@@ -809,7 +810,7 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat<!-- README:help:wt step --help-md -->```-wt step - Primitive operations (building blocks for workflows)+wt step — Primitive operations (building blocks for workflows)Usage: step <COMMAND>Commands:diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 64404830c..a1e51af44 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1,13 +1,9 @@//! README synchronization test//!-//! Verifies that README.md examples stay in sync with their source snapshots.-//! This replaces the Python `dev/update-readme.py` script with a native Rust test.+//! Verifies that README.md examples stay in sync with their source snapshots and help output.+//! Automatically updates help sections when out of sync.//!//! Run with: `cargo test --test integration readme_sync`-//!-//! To update README when snapshots change:-//! 1. Run this test to see which sections are out of sync-//! 2. Copy the expected content from the test output into README.mduse regex::Regex;use std::fs;@@ -23,9 +19,9 @@ static SNAPSHOT_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {.expect("Invalid marker regex")});-/// Regex to find README help markers+/// Regex to find README help markers (no wrapper - content is rendered markdown)static HELP_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {- Regex::new(r"(?s)<!-- README:help:(.+?) -->\n```\n(.*?)```\n<!-- README:end -->")+ Regex::new(r"(?s)<!-- README:help:(.+?) -->\n(.*?)\n<!-- README:end -->").expect("Invalid help marker regex")});@@ -181,7 +177,7 @@ fn get_help_output(command: &str, project_root: &Path) -> Result<String, String>let help_output = strip_ansi(&help_output);// Trim trailing whitespace from each line and join- let result = help_output+ let help_output = help_output.lines().map(|line| line.trim_end()).collect::<Vec<_>>()@@ -189,9 +185,96 @@ fn get_help_output(command: &str, project_root: &Path) -> Result<String, String>.trim().to_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+ 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+ let first_line = first_line.replacen(" - ", " — ", 1);++ if let Some(header_pos) = rest.find("\n## ") {+ // Split at first H2 header+ let (synopsis, docs) = rest.split_at(header_pos);+ format!(+ "```\n{}{}\n```\n{}",+ first_line,+ synopsis,+ docs.trim_start_matches('\n')+ )+ } else {+ // No documentation section, wrap everything in code block+ format!("```\n{}{}\n```", first_line, rest)+ }+ } else {+ // Single line output+ help_output.replacen(" - ", " — ", 1)+ };+Ok(result)}+/// Update a section in the README content, returning (new content, updated count, total count)+fn update_readme_section(+ content: &str,+ pattern: &Regex,+ get_replacement: impl Fn(&str) -> Result<String, String>,+ wrapper: (&str, &str),+) -> Result<(String, usize, usize), Vec<String>> {+ let mut result = content.to_string();+ let mut errors = Vec::new();+ let mut updated = 0;++ // Collect all matches first (to avoid borrowing issues)+ let matches: Vec<_> = pattern+ .captures_iter(content)+ .map(|cap| {+ let full_match = cap.get(0).unwrap();+ let id = cap.get(1).unwrap().as_str().to_string();+ let current = normalize_readme_content(cap.get(2).unwrap().as_str());+ (full_match.start(), full_match.end(), id, current)+ })+ .collect();++ let total = matches.len();++ // Process in reverse order to preserve positions+ for (start, end, id, current) in matches.into_iter().rev() {+ let expected = match get_replacement(&id) {+ Ok(content) => content,+ Err(e) => {+ errors.push(format!("❌ {}: {}", id, e));+ continue;+ }+ };++ if current != expected {+ // Build replacement+ let replacement = if wrapper.0.is_empty() {+ // No wrapper (help sections - rendered markdown)+ format!(+ "<!-- README:help:{} -->\n{}\n<!-- README:end -->",+ id, expected+ )+ } else {+ // With wrapper (snapshot sections)+ format!(+ "<!-- README:snapshot:{} -->\n{}\n{}\n{}\n<!-- README:end -->",+ id, wrapper.0, expected, wrapper.1+ )+ };+ result.replace_range(start..end, &replacement);+ updated += 1;+ }+ }++ if errors.is_empty() {+ Ok((result, updated, total))+ } else {+ Err(errors)+ }+}+#[test]fn test_readme_examples_are_in_sync() {let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));@@ -201,6 +284,8 @@ fn test_readme_examples_are_in_sync() {let mut errors = Vec::new();let mut checked = 0;+ let mut updated_content = readme_content.clone();+ let mut total_updated = 0;// Check snapshot markersfor cap in SNAPSHOT_MARKER_PATTERN.captures_iter(&readme_content) {@@ -228,44 +313,39 @@ fn test_readme_examples_are_in_sync() {}}- // Check help markers- for cap in HELP_MARKER_PATTERN.captures_iter(&readme_content) {- let command = cap.get(1).unwrap().as_str();- let current_content = normalize_readme_content(cap.get(2).unwrap().as_str());- checked += 1;-- // Get help output for the command- let expected = match get_help_output(command, project_root) {- Ok(content) => content,- Err(e) => {- errors.push(format!("❌ {}: {}", command, e));- continue;- }- };-- // Compare- if current_content != expected {- errors.push(format!(- "❌ {} is out of sync\n\n--- Current (in README) ---\n{}\n\n--- Expected (from --help) ---\n{}\n",- command, current_content, expected- ));+ // Update help markers (no wrapper - content is rendered markdown)+ let project_root_clone = project_root.to_path_buf();+ match update_readme_section(+ &updated_content,+ &HELP_MARKER_PATTERN,+ |cmd| get_help_output(cmd, &project_root_clone),+ ("", ""),+ ) {+ Ok((new_content, updated_count, total_count)) => {+ updated_content = new_content;+ total_updated += updated_count;+ checked += total_count;}+ Err(errs) => errors.extend(errs),}if checked == 0 {panic!("No README markers found in README.md");}+ // Write updates+ if total_updated > 0 {+ fs::write(&readme_path, &updated_content).expect("Failed to write README.md");+ println!("✅ Updated {} sections in README.md", total_updated);+ }+if !errors.is_empty() {panic!("README examples are out of sync:\n\n{}\n\n\- To fix: Update the README sections with the expected content above.\n\- Checked {} markers, {} out of sync.",+ Checked {} markers, {} errors.",errors.join("\n"),checked,errors.len());}-- // Test passes implicitly - no errors found}