Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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);