Skip to content

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.md
index 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 worktree
Usage: switch [OPTIONS] <BRANCH>
Arguments:
@@ -331,6 +331,7 @@ Options:
-h, --help
Print 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 branch
Usage: merge [OPTIONS] [TARGET]
Arguments:
@@ -456,6 +457,7 @@ Options:
-h, --help
Print help (see a summary with '-h')
+```
## Operation
Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
@@ -514,7 +516,6 @@ Skip all hooks:
```bash
wt 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 branch
Usage: remove [OPTIONS] [WORKTREES]...
Arguments:
@@ -544,6 +545,7 @@ Options:
-h, --help
Print help (see a summary with '-h')
+```
## Operation
Removes worktree directory, git metadata, and branch. Requires clean working tree.
@@ -599,7 +601,6 @@ Switch to default in main:
```bash
wt 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 branches
Usage: list [OPTIONS]
Options:
@@ -635,6 +636,7 @@ Options:
-h, --help
Print help (see a summary with '-h')
+```
## Columns
- **Branch:** Branch name
@@ -718,7 +720,6 @@ jq '.[] | select(.status.main_divergence == "Ahead")'
# Find locked worktrees
jq '.[] | 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 integration
Usage: config <COMMAND>
Commands:
@@ -744,6 +745,7 @@ Options:
-h, --help
Print help (see a summary with '-h')
+```
## Setup Guide
1. 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.rs
index 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.md
use 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 markers
for 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
}