warn when pager is missing instead of silently falling back

when a configured pager (via BAT_PAGER, PAGER, or --pager) is not found,
bat now shows a warning message before falling back to stdout. this helps
users understand why their pager isn't running and makes it obvious when
there's a typo or PATH issue.

fixes issue #2904

CHANGELOG.md

@@ -10,6 +10,7 @@
 - Improve native man pages and command help syntax highlighting by stripping overstriking, see #3517 (@akirk)
 
 ## Bugfixes
+- Report error when pager is missing instead of silently falling back, see #3588 (@IMaloney)
 - Fix crash with BusyBox `less` on Windows, see #3527 (@Anchal-T)
 - Fix `bat cache --help` failing with 'unexpected argument' error, see #3580 and #3560 (@NORMAL-EX)
 - `--help` now correctly honors `--pager=builtin`. See #3516 (@keith-hall)

src/output.rs

@@ -105,6 +105,10 @@ impl OutputType {
         let resolved_path = match grep_cli::resolve_binary(&pager.bin) {
             Ok(path) => path,
             Err(_) => {
+                crate::bat_warning!(
+                    "Pager '{}' not found, outputting to stdout instead",
+                    pager.bin.to_string_lossy()
+                );
                 return Ok(OutputType::stdout());
             }
         };
@@ -174,7 +178,13 @@ impl OutputType {
         Ok(p.stdin(Stdio::piped())
             .spawn()
             .map(OutputType::Pager)
-            .unwrap_or_else(|_| OutputType::stdout()))
+            .unwrap_or_else(|_| {
+                crate::bat_warning!(
+                    "Pager '{}' not found, outputting to stdout instead",
+                    &pager.bin
+                );
+                OutputType::stdout()
+            }))
     }
 
     pub(crate) fn stdout() -> Self {

tests/integration_tests.rs

@@ -1425,6 +1425,21 @@ fn pager_failed_to_parse() {
         .stderr(predicate::str::contains("Could not parse pager command"));
 }
 
+#[test]
+#[serial]
+fn pager_missing_warning() {
+    bat()
+        .env("BAT_PAGER", "nonexistent-pager-xyz-missing")
+        .arg("--paging=always")
+        .arg("test.txt")
+        .assert()
+        .success()
+        .stderr(predicate::str::contains("[bat warning]"))
+        .stderr(predicate::str::contains("not found"))
+        .stderr(predicate::str::contains("nonexistent-pager-xyz-missing"))
+        .stdout(predicate::str::contains("hello world\n"));
+}
+
 #[test]
 #[serial]
 fn env_var_bat_paging() {