Skip to content

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.md
index 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()` in
Similarly, `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 workflow
Demo 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.md
index edf8342d0..aab8537ca 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -6,7 +6,7 @@ weight = 15
group = "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 integration
Usage: wt config [OPTIONS] <COMMAND>
@@ -245,3 +243,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt config --help-page` -->
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 824f8cee7..9260315fd 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -6,7 +6,7 @@ weight = 17
group = "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 hooks
Usage: wt hook [OPTIONS] <COMMAND>
@@ -323,3 +321,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt hook --help-page` -->
diff --git a/docs/content/list.md b/docs/content/list.md
index 5c2503627..4fbc5ef42 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -6,7 +6,7 @@ weight = 11
group = "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 branches
Usage: wt list [OPTIONS]
@@ -224,3 +222,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt list --help-page` -->
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 30c91011a..afa0422ae 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -6,7 +6,7 @@ weight = 13
group = "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 branch
Usage: wt merge [OPTIONS] [TARGET]
@@ -117,3 +115,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt merge --help-page` -->
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 21934e8da..ff4e34b5b 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -6,7 +6,7 @@ weight = 12
group = "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 branch
Usage: wt remove [OPTIONS] [WORKTREES]...
@@ -103,3 +101,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt remove --help-page` -->
diff --git a/docs/content/select.md b/docs/content/select.md
index 9060d4df2..327fdefbd 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -6,7 +6,7 @@ weight = 14
group = "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, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt select --help-page` -->
diff --git a/docs/content/step.md b/docs/content/step.md
index fd42c0d3a..b5597b72c 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -6,7 +6,7 @@ weight = 16
group = "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 operations
Usage: wt step [OPTIONS] <COMMAND>
@@ -70,3 +68,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt step --help-page` -->
diff --git a/docs/content/switch.md b/docs/content/switch.md
index b5d50a58d..93d4f41fe 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -6,7 +6,7 @@ weight = 10
group = "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 worktree
Usage: wt switch [OPTIONS] <BRANCH>
@@ -117,3 +115,5 @@ Global Options:
-v, --verbose
Show commands and debug info
```
+
+<!-- END AUTO-GENERATED from `wt switch --help-page` -->
diff --git a/src/main.rs b/src/main.rs
index 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 markers
println!(
- "<!-- ⚠️ 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.rs
index 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(&current) {
+ let before = &current[..m.start()];
+ let after = &current[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;
}