Merge pull request #1342 from mitchellh/show-config

`+show-config` action

README.md

@@ -100,8 +100,20 @@ palette = 7=#a89984
 palette = 15=#fbf1c7
 ```
 
-While the set of config keys and values are not yet documented, they are
-discoverable in the [Config structure](https://github.com/mitchellh/ghostty/blob/main/src/config/Config.zig).
+You can view all available configuration options and their documentation
+by executing the command `ghostty +show-config --default --docs`. Note that
+this will output the full default configuration with docs to stdout, so
+you may want to pipe that through a pager, an editor, etc.
+
+> [!NOTE]
+>
+> You'll see a lot of weird blank configurations like `font-family =`. This
+> is a valid syntax to specify the default behavior (no value). The
+> `+show-config` outputs it so its clear that key is defaulting and also
+> to have something to attach the doc comment to.
+
+You can also see and read all available configuration options in the source
+[Config structure](https://github.com/mitchellh/ghostty/blob/main/src/config/Config.zig).
 The available keys are the keys verbatim, and their possible values are typically
 documented in the comments. You also can search for the
 [public config files](https://github.com/search?q=path%3Aghostty%2Fconfig&type=code)
@@ -124,11 +136,13 @@ is in the "building Ghostty" section at the end of the README.
 
 In the debug output, you should see in the first 20 lines or so messages
 about loading (or not loading) a configuration file, as well as any errors
-it may have encountered. Ghostty currently ignores errors and treats it
-as if the configuration had not been set, so this is the best place to look
-if something isn't working.
+it may have encountered. Configuration errors are also shown in a dedicated
+window on both macOS and Linux (GTK). Ghostty does not treat configuration
+errors as fatal and will fall back to default values for erroneous keys.
 
-Eventually, we'll have a better mechanism for showing errors to the user.
+You can also view the full configuration Ghostty is loading using
+`ghostty +show-config` from the command-line. Use the `--help` flag to
+additional options for that command.
 
 ### Themes
 

src/cli/action.zig

@@ -8,6 +8,7 @@ const version = @import("version.zig");
 const list_keybinds = @import("list_keybinds.zig");
 const list_themes = @import("list_themes.zig");
 const list_colors = @import("list_colors.zig");
+const show_config = @import("show_config.zig");
 
 /// Special commands that can be invoked via CLI flags. These are all
 /// invoked by using `+<action>` as a CLI flag. The only exception is
@@ -31,6 +32,9 @@ pub const Action = enum {
     /// List named RGB colors
     @"list-colors",
 
+    /// Dump the config to stdout
+    @"show-config",
+
     pub const Error = error{
         /// Multiple actions were detected. You can specify at most one
         /// action on the CLI otherwise the behavior desired is ambiguous.
@@ -119,6 +123,7 @@ pub const Action = enum {
             .@"list-keybinds" => try list_keybinds.run(alloc),
             .@"list-themes" => try list_themes.run(alloc),
             .@"list-colors" => try list_colors.run(alloc),
+            .@"show-config" => try show_config.run(alloc),
         };
     }
 

src/cli/list_keybinds.zig

@@ -4,7 +4,8 @@ const args = @import("args.zig");
 const Action = @import("action.zig").Action;
 const Arena = std.heap.ArenaAllocator;
 const Allocator = std.mem.Allocator;
-const Config = @import("../config/Config.zig");
+const configpkg = @import("../config.zig");
+const Config = configpkg.Config;
 
 pub const Options = struct {
     /// If true, print out the default keybinds instead of the ones
@@ -46,12 +47,7 @@ pub fn run(alloc: Allocator) !u8 {
     defer config.deinit();
 
     const stdout = std.io.getStdOut().writer();
-    var iter = config.keybind.set.bindings.iterator();
-    while (iter.next()) |next| {
-        const keys = next.key_ptr.*;
-        const value = next.value_ptr.*;
-        try stdout.print("{}={}\n", .{ keys, value });
-    }
+    try config.keybind.formatEntry(configpkg.entryFormatter("keybind", stdout));
 
     return 0;
 }

src/cli/show_config.zig

@@ -0,0 +1,84 @@
+const std = @import("std");
+const args = @import("args.zig");
+const Allocator = std.mem.Allocator;
+const Action = @import("action.zig").Action;
+const configpkg = @import("../config.zig");
+const Config = configpkg.Config;
+
+pub const Options = struct {
+    /// If true, do not load the user configuration, only load the defaults.
+    default: bool = false,
+
+    /// Only show the options that have been changed from the default.
+    /// This has no effect if `--default` is specified.
+    @"changes-only": bool = true,
+
+    /// If true print the documentation above each option as a comment,
+    /// if available.
+    docs: bool = false,
+
+    pub fn deinit(self: Options) void {
+        _ = self;
+    }
+
+    /// Enables "-h" and "--help" to work.
+    pub fn help(self: Options) !void {
+        _ = self;
+        return Action.help_error;
+    }
+};
+
+/// The "show-config" command shows the current configuration in a valid
+/// Ghostty configuration file format.
+///
+/// When executed without any arguments this will output the current
+/// configuration that is different from the default configuration. If you're
+/// using the default configuration this will output nothing.
+///
+/// If you are a new user and want to see all available options with
+/// documentation, run `ghostty +show-config --default --docs`.
+///
+/// The output is not in any specific order, but the order should be
+/// consistent between runs. The output is not guaranteed to be exactly
+/// match the input configuration files, but it will result in the same
+/// behavior. Comments, whitespace, and other formatting is not preserved
+/// from user configuration files.
+///
+/// Flags:
+///
+///   - "--default": Show the default configuration instead of loading
+///     the user configuration.
+///
+///   - "--changes-only": Only show the options that have been changed
+///     from the default. This has no effect if "--default" is specified.
+///
+///   - "--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".
+///
+pub fn run(alloc: Allocator) !u8 {
+    var opts: Options = .{};
+    defer opts.deinit();
+
+    {
+        var iter = try std.process.argsWithAllocator(alloc);
+        defer iter.deinit();
+        try args.parse(Options, alloc, &opts, &iter);
+    }
+
+    var config = if (opts.default) try Config.default(alloc) else try Config.load(alloc);
+    defer config.deinit();
+
+    const configfmt: configpkg.FileFormatter = .{
+        .alloc = alloc,
+        .config = &config,
+        .changed = !opts.default and opts.@"changes-only",
+        .docs = opts.docs,
+    };
+
+    // For some reason `std.fmt.format` isn't working here but it works in
+    // tests so we just do configfmt.format.
+    const stdout = std.io.getStdOut().writer();
+    try configfmt.format("", .{}, stdout);
+    return 0;
+}