diff --git a/README.md b/README.md index 3fcabc71c..be96b1a33 100644 --- a/README.md +++ b/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 diff --git a/src/cli/action.zig b/src/cli/action.zig index 2e3afb1c0..a7cbabf25 100644 --- a/src/cli/action.zig +++ b/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 `+` 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), }; } diff --git a/src/cli/list_keybinds.zig b/src/cli/list_keybinds.zig index 15df1815e..ed831837e 100644 --- a/src/cli/list_keybinds.zig +++ b/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; } diff --git a/src/cli/show_config.zig b/src/cli/show_config.zig new file mode 100644 index 000000000..c62dfe9f5 --- /dev/null +++ b/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; +}