cli: add pager support to +explain-config (#11940)

Add a new Pager type that wraps output to an external pager program when
stdout is a TTY, following the same conventions as git. The pager
command is resolved from $PAGER, falling back to `less`. An empty $PAGER
disables paging. If the pager fails to spawn, we fall back to stdout.

Previously, +explain-config wrote directly to stdout with no paging,
which meant long help text would scroll by. Now output is automatically
piped through the user's preferred pager when running interactively. A
--no-pager flag is available to disable this.

src/cli/Pager.zig

@@ -0,0 +1,93 @@
+//! A pager wraps output to an external pager program (like `less`) when
+//! stdout is a TTY. The pager command is resolved as:
+//!
+//!   `$GHOSTTY_PAGER` > `$PAGER` > `less`
+//!
+//! Setting either env var to an empty string disables paging.
+//! If stdout is not a TTY, writes go directly to stdout.
+const Pager = @This();
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const internal_os = @import("../os/main.zig");
+
+/// The pager child process, if one was spawned.
+child: ?std.process.Child = null,
+
+/// The buffered file writer used for both the pager pipe and direct
+/// stdout paths.
+file_writer: std.fs.File.Writer = undefined,
+
+/// Initialize the pager. If stdout is a TTY, this spawns the pager
+/// process. Otherwise, output goes directly to stdout.
+pub fn init(alloc: Allocator) Pager {
+    return .{ .child = initPager(alloc) };
+}
+
+/// Writes to the pager process if available; otherwise, stdout.
+pub fn writer(self: *Pager, buffer: []u8) *std.Io.Writer {
+    if (self.child) |child| {
+        self.file_writer = child.stdin.?.writer(buffer);
+    } else {
+        self.file_writer = std.fs.File.stdout().writer(buffer);
+    }
+    return &self.file_writer.interface;
+}
+
+/// Deinitialize the pager. Waits for the spawned process to exit.
+pub fn deinit(self: *Pager) void {
+    if (self.child) |*child| {
+        // Flush any remaining buffered data, close the pipe so the
+        // pager sees EOF, then wait for it to exit.
+        self.file_writer.interface.flush() catch {};
+        if (child.stdin) |stdin| {
+            stdin.close();
+            child.stdin = null;
+        }
+        _ = child.wait() catch {};
+    }
+
+    self.* = undefined;
+}
+
+fn initPager(alloc: Allocator) ?std.process.Child {
+    const stdout_file: std.fs.File = .stdout();
+    if (!stdout_file.isTty()) return null;
+
+    // Resolve the pager command: $GHOSTTY_PAGER > $PAGER > `less`.
+    // An empty value for either env var disables paging.
+    const ghostty_var = internal_os.getenv(alloc, "GHOSTTY_PAGER") catch null;
+    defer if (ghostty_var) |v| v.deinit(alloc);
+    const pager_var = internal_os.getenv(alloc, "PAGER") catch null;
+    defer if (pager_var) |v| v.deinit(alloc);
+
+    const cmd: ?[]const u8 = cmd: {
+        if (ghostty_var) |v| break :cmd if (v.value.len > 0) v.value else null;
+        if (pager_var) |v| break :cmd if (v.value.len > 0) v.value else null;
+        break :cmd "less";
+    };
+
+    if (cmd == null) return null;
+
+    var child: std.process.Child = .init(&.{cmd.?}, alloc);
+    child.stdin_behavior = .Pipe;
+    child.stdout_behavior = .Inherit;
+    child.stderr_behavior = .Inherit;
+
+    child.spawn() catch return null;
+    return child;
+}
+
+test "pager: non-tty" {
+    var pager: Pager = .init(std.testing.allocator);
+    defer pager.deinit();
+    try std.testing.expect(pager.child == null);
+}
+
+test "pager: default writer" {
+    var pager: Pager = .{};
+    defer pager.deinit();
+    try std.testing.expect(pager.child == null);
+    var buf: [4096]u8 = undefined;
+    const w = pager.writer(&buf);
+    try w.writeAll("hello");
+}

src/cli/explain_config.zig

@@ -6,6 +6,7 @@ const help_strings = @import("help_strings");
 const Config = @import("../config/Config.zig");
 const ConfigKey = @import("../config/key.zig").Key;
 const KeybindAction = @import("../input/Binding.zig").Action;
+const Pager = @import("Pager.zig");
 
 pub const Options = struct {
     /// The config option to explain. For example:
@@ -43,10 +44,13 @@ pub const Options = struct {
 ///
 ///   * `--option`: The name of the configuration option to explain.
 ///   * `--keybind`: The name of the keybind action to explain.
+///   * `--no-pager`: Disable automatic paging of output.
 pub fn run(alloc: Allocator) !u8 {
     var option_name: ?[]const u8 = null;
     var keybind_name: ?[]const u8 = null;
     var positional: ?[]const u8 = null;
+    var no_pager: bool = false;
+
     var iter = try args.argsIterator(alloc);
     defer iter.deinit();
     defer if (option_name) |s| alloc.free(s);
@@ -58,6 +62,8 @@ pub fn run(alloc: Allocator) !u8 {
             option_name = try alloc.dupe(u8, arg["--option=".len..]);
         } else if (std.mem.startsWith(u8, arg, "--keybind=")) {
             keybind_name = try alloc.dupe(u8, arg["--keybind=".len..]);
+        } else if (std.mem.eql(u8, arg, "--no-pager")) {
+            no_pager = true;
         } else if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
             return Action.help_error;
         } else if (!std.mem.startsWith(u8, arg, "-")) {
@@ -86,10 +92,10 @@ pub fn run(alloc: Allocator) !u8 {
     else
         explainOption(name) orelse explainKeybind(name);
 
-    var stdout: std.fs.File = .stdout();
+    var pager: Pager = if (!no_pager) .init(alloc) else .{};
+    defer pager.deinit();
     var buffer: [4096]u8 = undefined;
-    var stdout_writer = stdout.writer(&buffer);
-    const writer = &stdout_writer.interface;
+    const writer = pager.writer(&buffer);
 
     if (text) |t| {
         try writer.writeAll(t);
@@ -98,11 +104,11 @@ pub fn run(alloc: Allocator) !u8 {
         try writer.writeAll("Unknown: '");
         try writer.writeAll(name);
         try writer.writeAll("'.\n");
-        try stdout_writer.end();
+        try writer.flush();
         return 1;
     }
 
-    try stdout_writer.end();
+    try writer.flush();
     return 0;
 }
 

src/cli/show_config.zig

@@ -4,6 +4,7 @@ const Allocator = std.mem.Allocator;
 const Action = @import("ghostty.zig").Action;
 const configpkg = @import("../config.zig");
 const Config = configpkg.Config;
+const Pager = @import("Pager.zig");
 
 pub const Options = struct {
     /// If true, do not load the user configuration, only load the defaults.
@@ -17,6 +18,9 @@ pub const Options = struct {
     /// if available.
     docs: bool = false,
 
+    /// Disable automatic paging of output.
+    @"no-pager": bool = false,
+
     pub fn deinit(self: Options) void {
         _ = self;
     }
@@ -55,6 +59,8 @@ pub const Options = struct {
 ///   * `--docs`: Print the documentation above each option as a comment,
 ///     This is very noisy but is very useful to learn about available
 ///     options, especially paired with `--default`.
+///
+///   * `--no-pager`: Disable automatic paging of output.
 pub fn run(alloc: Allocator) !u8 {
     var opts: Options = .{};
     defer opts.deinit();
@@ -75,12 +81,12 @@ pub fn run(alloc: Allocator) !u8 {
         .docs = opts.docs,
     };
 
-    // For some reason `std.fmt.format` isn't working here but it works in
-    // tests so we just do configfmt.format.
-    var stdout: std.fs.File = .stdout();
+    var pager: Pager = if (!opts.@"no-pager") .init(alloc) else .{};
+    defer pager.deinit();
     var buffer: [4096]u8 = undefined;
-    var stdout_writer = stdout.writer(&buffer);
-    try configfmt.format(&stdout_writer.interface);
-    try stdout_writer.end();
+    const writer = pager.writer(&buffer);
+
+    try configfmt.format(writer);
+    try writer.flush();
     return 0;
 }