Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat: Sync README help examples to CLI output
Maximilian Roos0b2942289f3b
diff --git a/README.md b/README.mdindex 05bbfcc88..57b706ddb 100644--- a/README.md+++ b/README.md@@ -302,25 +302,35 @@ instead of duplicating logic:<details><summary><strong><code>wt switch [branch]</code></strong> - Switch to existing worktree or create a new one</summary>+<!-- README:help:wt switch --help-md -->```-Usage: wt switch [OPTIONS] <BRANCH>+wt switch - Switch to a worktree+Usage: switch [OPTIONS] <BRANCH>Arguments:- <BRANCH> Branch, path, '@' (HEAD), '-' (previous), or '^' (main)+ <BRANCH>+ Branch, path, '@' (HEAD), '-' (previous), or '^' (main)Options:- -c, --create Create a new branch- -b, --base <BASE> Base branch (defaults to default branch)- -x, --execute <EXECUTE> Command to run after switch- -f, --force Skip approval prompts- --no-verify Skip all project hooks- -h, --help Print help+ -c, --create+ Create a new branch-Global Options:- -C <path> Change working directory- --config <path> User config file path- -v, --verbose Show commands and debug info-```+ -b, --base <BASE>+ Base branch++ Defaults to default branch.++ -x, --execute <EXECUTE>+ Command to run after switch++ -f, --force+ Skip approval prompts++ --no-verify+ Skip all project hooks++ -h, --help+ Print help (see a summary with '-h')## Operation@@ -331,7 +341,6 @@ Global Options:- No branch creation### 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 }}`)3. Runs post-create hooks sequentially (blocking)@@ -349,62 +358,62 @@ Global Options:- Skip with `--no-verify`### post-start (parallel, background)-- Spawned after success message shown- Typically: dev servers, file watchers, editors- Run in background, failures logged but don't block- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`- Skip with `--no-verify`+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`++**Security:** Commands from project hooks require approval on first run.+Approvals are saved to user config. Use `--force` to bypass prompts.+See `wt config approvals --help`.+## ExamplesSwitch to existing worktree:--```+```bashwt switch feature-branch```Create new worktree from main:--```+```bashwt switch --create new-feature```Switch to previous worktree:--```+```bashwt switch -```Create from specific base:--```+```bashwt switch --create hotfix --base production```Create and run command:--```+```bashwt switch --create docs --execute "code ."```Skip hooks during creation:--```+```bashwt switch --create temp --no-verify```## ShortcutsUse `@` for current HEAD, `-` for previous, `^` for main:--```+```bashwt switch @ # Switch to current branch's worktreewt switch - # Switch to previous worktreewt switch --create new-feature --base=^ # Branch from main (default)wt switch --create bugfix --base=@ # Branch from current HEADwt remove @ # Remove current worktree```+```+<!-- README:end --></details>@@ -413,26 +422,43 @@ wt remove @ # Remove current worktree<details><summary><strong><code>wt merge [target]</code></strong> - Merge, push, and cleanup</summary>+<!-- README:help:wt merge --help-md -->```-Usage: wt merge [OPTIONS] [TARGET]+wt merge - Merge worktree into target branch+Usage: merge [OPTIONS] [TARGET]Arguments:- [TARGET] Target branch (defaults to default branch)+ [TARGET]+ Target branch++ Defaults to default branch.Options:- --no-squash Skip commit squashing- --no-commit Skip commit, squash, and rebase- --no-remove Keep worktree after merge- --no-verify Skip all project hooks- -f, --force Skip approval prompts- --stage <STAGE> What to stage before committing [default: all] [possible values: all, tracked, none]- -h, --help Print help+ --no-squash+ Skip commit squashing-Global Options:- -C <path> Change working directory- --config <path> User config file path- -v, --verbose Show commands and debug info-```+ --no-commit+ Skip commit, squash, and rebase++ --no-remove+ Keep worktree after merge++ --no-verify+ Skip all project hooks++ -f, --force+ Skip approval prompts++ --stage <STAGE>+ What to stage before committing [default: all]++ Possible values:+ - all: Stage everything: untracked files + unstaged tracked changes+ - tracked: Stage tracked changes only (like git add -u)+ - none: Stage nothing, commit only what's already in the index++ -h, --help+ Print help (see a summary with '-h')## Operation@@ -465,54 +491,62 @@ Fast-forward push to local target branch. Non-fast-forward pushes are rejected.Worktree and branch are removed. Skip with `--no-remove`.+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`++**Security:** Commands from project hooks require approval on first run.+Approvals are saved to user config. Use `--force` to bypass prompts.+See `wt config approvals --help`.+## ExamplesBasic merge to main:--```+```bashwt merge```Merge without squashing:--```+```bashwt merge --no-squash```Keep worktree after merging:--```+```bashwt merge --no-remove```Skip all hooks:--```+```bashwt merge --no-verify```+```+<!-- README:end --></details><details><summary><strong><code>wt remove [worktree]</code></strong> - Remove worktree and branch</summary>+<!-- README:help:wt remove --help-md -->```-Usage: wt remove [OPTIONS] [WORKTREES]...+wt remove - Remove worktree and branch+Usage: remove [OPTIONS] [WORKTREES]...Arguments:- [WORKTREES]... Worktree or branch (@ for current)+ [WORKTREES]...+ Worktree or branch (@ for current)Options:- --no-delete-branch Keep branch after removal- -D, --force-delete Delete unmerged branches- --no-background Run removal in foreground- -h, --help Print help+ --no-delete-branch+ Keep branch after removal-Global Options:- -C <path> Change working directory- --config <path> User config file path- -v, --verbose Show commands and debug info-```+ -D, --force-delete+ Delete unmerged branches++ --no-background+ Run removal in foreground++ -h, --help+ Print help (see a summary with '-h')## Operation@@ -541,40 +575,36 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or## ExamplesRemove current worktree and branch:--```+```bashwt remove```Remove specific worktree and branch:--```+```bashwt remove feature-branch```Remove worktree but keep branch:--```+```bashwt remove --no-delete-branch feature-branch```Remove multiple worktrees:--```+```bashwt remove old-feature another-branch```Remove in foreground (blocking):--```+```bashwt remove --no-background feature-branch```Switch to default in main:--```+```bashwt remove # (when already in main worktree)```+```+<!-- README:end --></details>@@ -583,45 +613,56 @@ wt remove # (when already in main worktree)<details><summary><strong><code>wt list</code></strong> - Show all worktrees and branches</summary>+<!-- README:help:wt list --help-md -->```-Usage: wt list [OPTIONS]+wt list - List worktrees and optionally branches+Usage: list [OPTIONS]Options:- --format <FORMAT> Output format (table, json) [default: table]- --branches Include branches without worktrees- --remotes Include remote branches- --full Show CI, conflicts, diffs- --progressive Force progressive (or --no-progressive)- -h, --help Print help+ --format <FORMAT>+ Output format (table, json)-Global Options:- -C <path> Change working directory- --config <path> User config file path- -v, --verbose Show commands and debug info-```+ [default: table]++ --branches+ Include branches without worktrees++ --remotes+ Include remote branches++ --full+ Show CI, conflicts, diffs++ --progressive+ Show fast info immediately, update with slow info++ Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.++ -h, --help+ Print help (see a summary with '-h')## Columns- **Branch:** Branch name-- **Status:** Quick status symbols (see STATUS SYMBOLS below)+- **Status:** Quick status symbols (see Status Symbols below)- **HEAD±:** Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)- **main↕:** Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)-- **main…± (--full):** Line diffs in commits ahead of main (+added -deleted)+- **main…±** (`--full`): Line diffs in commits ahead of main (+added -deleted)- **Path:** Worktree directory location-- **Remote⇅:** Commits ahead↑/behind↓ relative to tracking branch (e.g. origin/branch)-- **CI (--full):** CI pipeline status (tries PR/MR checks first, falls back to branch workflows)- - ● passed (green) - All checks passed- - ● running (blue) - Checks in progress- - ● failed (red) - Checks failed- - ● conflicts (yellow) - Merge conflicts with base- - ● no-ci (gray) - PR/MR or workflow found but no checks configured- - (blank) - No PR/MR or workflow found, or gh/glab CLI unavailable+- **Remote⇅:** Commits ahead↑/behind↓ relative to tracking branch (e.g. `origin/branch`)+- **CI** (`--full`): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)+ - `●` **passed** (green) - All checks passed+ - `●` **running** (blue) - Checks in progress+ - `●` **failed** (red) - Checks failed+ - `●` **conflicts** (yellow) - Merge conflicts with base+ - `●` **no-ci** (gray) - PR/MR or workflow found but no checks configured+ - (blank) - No PR/MR or workflow found, or `gh`/`glab` CLI unavailable- (dimmed) - Stale: unpushed local changes differ from PR/MR head- **Commit:** Short commit hash (8 chars)- **Age:** Time since last commit (relative)- **Message:** Last commit message (truncated)-**STATUS SYMBOLS:**+## Status SymbolsOrder: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`@@ -646,15 +687,14 @@ Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`- `⌫` Prunable worktree (directory missing, can be pruned)- `⊠` Locked worktree (protected from auto-removal)-_Rows are dimmed when no unique work (≡ matches main OR ∅ no commits)._+*Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).*-**JSON OUTPUT:**+## JSON OutputUse `--format=json` for structured data. Each object contains two status maps-with the same fields in the same order as STATUS SYMBOLS above:+with the same fields in the same order as Status Symbols above:**`status`** - variant names for querying:-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`- `git_operation`: `""` | `"Rebase"` | `"Merge"`@@ -684,14 +724,18 @@ jq '.[] | select(.status.main_divergence == "Ahead")'# Find locked worktreesjq '.[] | select(.locked != null)'```+```+<!-- README:end --></details><details><summary><strong><code>wt config</code></strong> - Manage configuration</summary>+<!-- README:help:wt config --help-md -->```-Usage: wt config [OPTIONS] <COMMAND>+wt config - Manage configuration and shell integration+Usage: config <COMMAND>Commands:shell Shell integration setup@@ -700,79 +744,97 @@ Commands:refresh-cache Refresh default branch from remotestatus Manage branch status markersapprovals Manage command approvals+ help Print this message or the help of the given subcommand(s)Options:- -h, --help Print help+ -h, --help+ Print help (see a summary with '-h')-Global Options:- -C <path> Change working directory- --config <path> User config file path- -v, --verbose Show commands and debug info-```--**LLM SETUP GUIDE:**--Enable LLM commit messages--1. Install an LLM tool (llm, aichat)+## Setup Guide+1. Set up shell integration```bash- uv tool install -U llm+ wt config shell install```-2. Configure a model-- For Claude:-+ Or manually add to your shell config:```bash- llm install llm-anthropic- llm keys set anthropic- # Paste your API key from: https://console.anthropic.com/settings/keys- llm models default claude-sonnet-4-5+ eval "$(wt config shell init bash)"```- For OpenAI:-+2. (Optional) Create config file```bash- llm keys set openai- # Paste your API key from: https://platform.openai.com/api-keys+ wt config create```-3. Test it works+ This creates ~/.config/worktrunk/config.toml with examples.- ```bash- llm "say hello"- ```--4. Configure worktrunk-- Add to `~/.config/worktrunk/config.toml`:+3. (Optional) Enable LLM commit messages+ Install: `uv tool install -U llm`+ Configure: `llm keys set anthropic`+ Add to config.toml:```toml[commit-generation]command = "llm"- ```+ ```bash++## LLM Setup Details++For Claude:+```bash+llm install llm-anthropic+llm keys set anthropic+llm models default claude-3.5-sonnet+```++For OpenAI:+```bash+llm keys set openai+```+Use `wt config list` to view your current configuration.Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat+## Configuration Files++**Global config** (user settings):+- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)+- Run `wt config create` to generate with documented examples++**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><details><summary><strong><code>wt step</code></strong> - Building blocks for workflows</summary>-Primitive operations that can be composed into custom workflows:+<!-- README:help:wt step --help-md -->+```+wt step - Primitive operations (building blocks for workflows)+Usage: step <COMMAND>-- `wt step commit` - Commit changes with LLM message-- `wt step squash [target]` - Squash commits with LLM message-- `wt step push [target]` - Push changes to local target branch-- `wt step rebase [target]` - Rebase onto target-- `wt step post-create` - Run post-create hook-- `wt step post-start` - Run post-start hook-- `wt step pre-commit` - Run pre-commit hook-- `wt step pre-merge` - Run pre-merge hook-- `wt step post-merge` - Run post-merge hook+Commands:+ commit Commit changes with LLM message+ squash Squash commits with LLM message+ push Push changes to local target branch+ rebase Rebase onto target+ post-create Run post-create hook+ post-start Run post-start hook+ pre-commit Run pre-commit hook+ pre-merge Run pre-merge hook+ post-merge Run post-merge hook+ help Print this message or the help of the given subcommand(s)-See `wt step --help` for details.+Options:+ -h, --help+ Print help+```+<!-- README:end --></details>diff --git a/src/cli.rs b/src/cli.rsindex 8d60ff113..29d01d1db 100644--- a/src/cli.rs+++ b/src/cli.rs@@ -158,7 +158,7 @@ wt config shell init fish | sourceZsh (~/.zshrc):```zsheval "$(wt config shell init zsh)"-```+```bash## Auto Setup@@ -177,17 +177,17 @@ Use `wt config shell install` to automatically add to your shell config."#)]#[command(after_long_help = r#"## Auto SetupDetects existing shell config files and adds integration:-```+```bashwt config shell install```Install for specific shell only:-```+```bashwt config shell install zsh```Skip confirmation prompt:-```+```bashwt config shell install --force```"#)]Install {@@ -303,17 +303,17 @@ commands.## ExamplesPre-approve all commands for current project:-```+```bashwt config approvals ask```Clear approvals for current project:-```+```bashwt config approvals clear```Clear global approvals:-```+```bashwt config approvals clear --global```"#)]Approvals {@@ -474,17 +474,17 @@ pub enum Commands {after_long_help = r#"## Setup Guide1. Set up shell integration- ```+ ```bashwt config shell install```Or manually add to your shell config:- ```+ ```basheval "$(wt config shell init bash)"```2. (Optional) Create config file- ```+ ```bashwt config create```@@ -498,19 +498,19 @@ pub enum Commands {```toml[commit-generation]command = "llm"- ```+ ```bash## LLM Setup DetailsFor Claude:-```+```bashllm install llm-anthropicllm keys set anthropicllm models default claude-3.5-sonnet```For OpenAI:-```+```bashllm keys set openai```@@ -702,39 +702,39 @@ See `wt config approvals --help`.## ExamplesSwitch to existing worktree:-```+```bashwt switch feature-branch```Create new worktree from main:-```+```bashwt switch --create new-feature```Switch to previous worktree:-```+```bashwt switch -```Create from specific base:-```+```bashwt switch --create hotfix --base production```Create and run command:-```+```bashwt switch --create docs --execute "code ."```Skip hooks during creation:-```+```bashwt switch --create temp --no-verify```## ShortcutsUse `@` for current HEAD, `-` for previous, `^` for main:-```+```bashwt switch @ # Switch to current branch's worktreewt switch - # Switch to previous worktreewt switch --create new-feature --base=^ # Branch from main (default)@@ -797,32 +797,32 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or## ExamplesRemove current worktree and branch:-```+```bashwt remove```Remove specific worktree and branch:-```+```bashwt remove feature-branch```Remove worktree but keep branch:-```+```bashwt remove --no-delete-branch feature-branch```Remove multiple worktrees:-```+```bashwt remove old-feature another-branch```Remove in foreground (blocking):-```+```bashwt remove --no-background feature-branch```Switch to default in main:-```+```bashwt remove # (when already in main worktree)```"#)]Remove {@@ -884,22 +884,22 @@ See `wt config approvals --help`.## ExamplesBasic merge to main:-```+```bashwt merge```Merge without squashing:-```+```bashwt merge --no-squash```Keep worktree after merging:-```+```bashwt merge --no-remove```Skip all hooks:-```+```bashwt merge --no-verify```"#)]Merge {diff --git a/src/main.rs b/src/main.rsindex d59245746..70e5122d6 100644--- a/src/main.rs+++ b/src/main.rs@@ -44,12 +44,34 @@ fn maybe_handle_help_with_pager() -> bool {use clap::ColorChoice;use clap::error::ErrorKind;+ let args: Vec<String> = std::env::args().collect();++ // Check for --help-md flag (output raw markdown without ANSI rendering)+ if args.iter().any(|a| a == "--help-md") {+ let mut cmd = cli::build_command();+ // Filter out --help-md and add --help for clap+ let filtered_args: Vec<String> = args+ .iter()+ .map(|a| {+ if a == "--help-md" {+ "--help".to_string()+ } else {+ a.clone()+ }+ })+ .collect();+ let target = help_resolver::resolve_target_command(&mut cmd, filtered_args);+ let help = target.render_long_help().to_string(); // Raw markdown, no ANSI+ println!("{}", help);+ process::exit(0);+ }+let mut cmd = cli::build_command();cmd = cmd.color(ColorChoice::Always); // Force clap to always emit ANSI codes// DON'T render markdown yet - let clap generate help first- match cmd.try_get_matches_from_mut(std::env::args()) {+ match cmd.try_get_matches_from_mut(args) {Ok(_) => false, // Normal args, not helpErr(err) => {match err.kind() {diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 87ca32b68..64404830c 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -12,16 +12,23 @@use regex::Regex;use std::fs;use std::path::Path;+use std::process::Command;use std::sync::LazyLock;/// Regex to find README snapshot markers-static MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {+static SNAPSHOT_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {Regex::new(r"(?s)<!-- README:snapshot:([^\s]+) -->\n```\w*\n(?:\$ [^\n]+\n)?(.*?)```\n<!-- README:end -->",).expect("Invalid marker regex")});+/// Regex to find README help markers+static HELP_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {+ Regex::new(r"(?s)<!-- README:help:(.+?) -->\n```\n(.*?)```\n<!-- README:end -->")+ .expect("Invalid help marker regex")+});+/// Regex to strip ANSI escape codes (actual escape sequences)static ANSI_ESCAPE_REGEX: LazyLock<Regex> =LazyLock::new(|| Regex::new(r"\x1b\[[0-9;]*m").expect("Invalid ANSI regex"));@@ -112,12 +119,77 @@ fn normalize_for_readme(content: &str) -> String {let content = TMPDIR_REGEX.replace_all(&content, "../repo.$1");let content = REPO_REGEX.replace_all(&content, "../repo");- // Trim trailing whitespace from each line (matches pre-commit behavior)+ // Trim trailing whitespace from each line and overall (matches pre-commit behavior)content.lines().map(|line| line.trim_end()).collect::<Vec<_>>().join("\n")+ .trim()+ .to_string()+}++/// Normalize README content for comparison+fn normalize_readme_content(content: &str) -> String {+ content+ .lines()+ .map(|line| line.trim_end())+ .collect::<Vec<_>>()+ .join("\n")+ .trim()+ .to_string()+}++/// Get help output for a command+///+/// Expected format: `wt <subcommand> --help-md`+fn get_help_output(command: &str, project_root: &Path) -> Result<String, String> {+ let args: Vec<&str> = command.split_whitespace().collect();+ if args.is_empty() {+ return Err("Empty command".to_string());+ }++ // Validate command format+ if args.first() != Some(&"wt") {+ return Err(format!("Command must start with 'wt': {}", command));+ }++ // Validate it ends with --help-md+ if args.last() != Some(&"--help-md") {+ return Err(format!("Command must end with '--help-md': {}", command));+ }++ // Build the cargo run command+ let output = Command::new("cargo")+ .args(["run", "-q", "--"])+ .args(&args[1..]) // Skip "wt" prefix+ .current_dir(project_root)+ .output()+ .map_err(|e| format!("Failed to run command: {}", e))?;++ let stdout = String::from_utf8_lossy(&output.stdout);+ let stderr = String::from_utf8_lossy(&output.stderr);++ // Help goes to stdout+ let help_output = if !stdout.is_empty() {+ stdout.to_string()+ } else {+ stderr.to_string()+ };++ // Strip ANSI codes+ let help_output = strip_ansi(&help_output);++ // Trim trailing whitespace from each line and join+ let result = help_output+ .lines()+ .map(|line| line.trim_end())+ .collect::<Vec<_>>()+ .join("\n")+ .trim()+ .to_string();++ Ok(result)}#[test]@@ -130,18 +202,10 @@ fn test_readme_examples_are_in_sync() {let mut errors = Vec::new();let mut checked = 0;- for cap in MARKER_PATTERN.captures_iter(&readme_content) {+ // Check snapshot markers+ for cap in SNAPSHOT_MARKER_PATTERN.captures_iter(&readme_content) {let snap_path = cap.get(1).unwrap().as_str();- // Normalize README content: trim trailing whitespace from each line- let current_content = cap- .get(2)- .unwrap()- .as_str()- .lines()- .map(|line| line.trim_end())- .collect::<Vec<_>>()- .join("\n");- let current_content = current_content.trim();+ let current_content = normalize_readme_content(cap.get(2).unwrap().as_str());checked += 1;let full_path = project_root.join(snap_path);@@ -155,8 +219,6 @@ fn test_readme_examples_are_in_sync() {}};- let expected = expected.trim();-// Compareif current_content != expected {errors.push(format!(@@ -166,13 +228,37 @@ 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+ ));+ }+ }+if checked == 0 {- panic!("No README:snapshot markers found in README.md");+ panic!("No README markers found in README.md");}if !errors.is_empty() {panic!(- "README examples are out of sync with snapshots:\n\n{}\n\n\+ "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.",errors.join("\n"),