Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat: -h never opens pager, --help uses pager (git convention) (#651)
Maximilian Roosfcd707c81675
diff --git a/src/commands/config.rs b/src/commands/config.rsindex a37a2a7c1..9c46b4eb3 100644--- a/src/commands/config.rs+++ b/src/commands/config.rs@@ -171,8 +171,8 @@ pub fn handle_config_show(full: bool) -> anyhow::Result<()> {show_output.push('\n');render_runtime_info(&mut show_output)?;- // Display through pager- if let Err(e) = show_help_in_pager(&show_output) {+ // Display through pager (config show is always long-form output)+ if let Err(e) = show_help_in_pager(&show_output, true) {log::debug!("Pager invocation failed: {}", e);// Fall back to direct output via eprintln (matches help behavior)worktrunk::styling::eprintln!("{}", show_output);@@ -1117,7 +1117,7 @@ pub fn handle_state_get(key: &str, branch: Option<String>) -> anyhow::Result<()>render_log_files(&mut out, &repo)?;// Display through pager (fall back to stderr if pager unavailable)- if show_help_in_pager(&out).is_err() {+ if show_help_in_pager(&out, true).is_err() {worktrunk::styling::eprintln!("{}", out);}}@@ -1603,7 +1603,7 @@ fn handle_state_show_table(repo: &Repository) -> anyhow::Result<()> {render_log_files(&mut out, repo)?;// Display through pager (fall back to stderr if pager unavailable)- if let Err(e) = show_help_in_pager(&out) {+ if let Err(e) = show_help_in_pager(&out, true) {log::debug!("Pager invocation failed: {}", e);// Fall back to direct output via eprintln (matches help behavior)worktrunk::styling::eprintln!("{}", out);diff --git a/src/commands/hook_commands.rs b/src/commands/hook_commands.rsindex d1ddfac8f..d6e30bfe7 100644--- a/src/commands/hook_commands.rs+++ b/src/commands/hook_commands.rs@@ -424,7 +424,7 @@ pub fn handle_hook_show(hook_type_filter: Option<&str>, expanded: bool) -> anyho)?;// Display through pager (fall back to stderr if pager unavailable)- if show_help_in_pager(&output).is_err() {+ if show_help_in_pager(&output, true).is_err() {worktrunk::styling::eprintln!("{}", output);}diff --git a/src/help.rs b/src/help.rsindex 50d160377..dffdfd9e7 100644--- a/src/help.rs+++ b/src/help.rs@@ -14,9 +14,13 @@ use crate::cli;/// Custom help handling for pager support and markdown rendering.////// We intercept help requests to provide:-/// 1. **Pager support**: Help is shown through the detected pager (git-style precedence)+/// 1. **Pager support**: Long help (`--help`) shown through pager, short (`-h`) prints directly/// 2. **Markdown rendering**: `## Headers` become green, code blocks are dimmed///+/// This follows git's convention:+/// - `-h` never opens a pager (short help, muscle-memory safe)+/// - `--help` opens a pager when content doesn't fit (via less -F flag)+////// Uses `Error::render()` to get clap's pre-formatted help, which already/// respects `-h` (short) vs `--help` (long) distinction.///@@ -27,6 +31,9 @@ pub fn maybe_handle_help_with_pager() -> bool {let args: Vec<String> = std::env::args().collect();+ // --help uses pager, -h prints directly (git convention)+ let use_pager = args.iter().any(|a| a == "--help");+// Check for --help-page flag (output full doc page with frontmatter)if args.iter().any(|a| a == "--help-page") {handle_help_page(&args);@@ -92,7 +99,8 @@ pub fn maybe_handle_help_with_pager() -> bool {// show_help_in_pager checks if stdout or stderr is a TTY.// If neither is a TTY (e.g., `wt --help &>file`), it skips the pager.- if let Err(e) = crate::help_pager::show_help_in_pager(&help) {+ // use_pager=false for -h (short help), true for --help (long help)+ if let Err(e) = crate::help_pager::show_help_in_pager(&help, use_pager) {log::debug!("Pager invocation failed: {}", e);eprintln!("{}", help);}diff --git a/src/help_pager.rs b/src/help_pager.rsindex d697f684d..f1c9adbec 100644--- a/src/help_pager.rs+++ b/src/help_pager.rs@@ -64,7 +64,14 @@ fn detect_help_pager() -> Option<String> {/// Show help text through a pager with TTY access for interactive scrolling.///-/// Only uses pager when stdout or stderr is a terminal. Falls back to direct output if:+/// The `use_pager` flag controls whether to attempt pager display:+/// - `true` (--help): Uses pager when available and terminal is detected+/// - `false` (-h): Always prints directly to stderr, never uses pager+///+/// This follows git's convention where `-h` never opens a pager (muscle-memory safe)+/// while `--help` uses a pager for longer content.+///+/// Even when `use_pager=true`, falls back to direct output if:/// - No pager configured (prints to stderr)/// - Neither stdout nor stderr is a TTY (prints to stderr)/// - Pager spawn fails (prints to stderr)@@ -72,7 +79,14 @@ fn detect_help_pager() -> Option<String> {/// Note: All fallbacks output to stderr for consistency with pager behavior/// (which sends output to stderr via `>&2`). This ensures `config show`/// works correctly since stdout is reserved for data output.-pub(crate) fn show_help_in_pager(help_text: &str) -> std::io::Result<()> {+pub(crate) fn show_help_in_pager(help_text: &str, use_pager: bool) -> std::io::Result<()> {+ // Short help (-h) never uses a pager+ if !use_pager {+ log::debug!("Short help (-h) requested, printing directly to stderr");+ eprint!("{}", help_text);+ return Ok(());+ }+let Some(pager_cmd) = detect_help_pager() else {log::debug!("No pager configured, printing help directly to stderr");eprint!("{}", help_text);