feat(config): generate default template when config file is not found

Closes #3203

src/config/Config.zig

@@ -2586,12 +2586,33 @@ pub fn loadFile(self: *Config, alloc: Allocator, path: []const u8) !void {
 }
 
 /// Load optional configuration file from `path`. All errors are ignored.
-pub fn loadOptionalFile(self: *Config, alloc: Allocator, path: []const u8) void {
+pub fn loadOptionalFile(self: *Config, alloc: Allocator, path: []const u8, comptime create_template: bool) void {
     self.loadFile(alloc, path) catch |err| switch (err) {
-        error.FileNotFound => std.log.info(
-            "optional config file not found, not loading path={s}",
-            .{path},
-        ),
+        error.FileNotFound => if (create_template) {
+            std.log.info(
+                "optional config file not found, creating template config file: path={s}",
+                .{path},
+            );
+
+            const file = std.fs.createFileAbsolute(path, .{}) catch |e| {
+                std.log.info(
+                    "failed to create template config file at path={s}: {}",
+                    .{ path, e },
+                );
+                return;
+            };
+            std.fmt.format(file.writer(), @embedFile("./config-template"), .{ .path = path }) catch |e| {
+                std.log.info(
+                    "failed to write template config file to path={s}: {}",
+                    .{ path, e },
+                );
+            };
+        } else {
+            std.log.info(
+                "optional config file not found, not loading path={s}",
+                .{path},
+            );
+        },
         else => std.log.warn(
             "error reading optional config file, not loading err={} path={s}",
             .{ err, path },
@@ -2607,12 +2628,12 @@ pub fn loadOptionalFile(self: *Config, alloc: Allocator, path: []const u8) void
 pub fn loadDefaultFiles(self: *Config, alloc: Allocator) !void {
     const xdg_path = try internal_os.xdg.config(alloc, .{ .subdir = "ghostty/config" });
     defer alloc.free(xdg_path);
-    self.loadOptionalFile(alloc, xdg_path);
+    self.loadOptionalFile(alloc, xdg_path, comptime builtin.os.tag == .linux);
 
     if (comptime builtin.os.tag == .macos) {
         const app_support_path = try internal_os.macos.appSupportDir(alloc, "config");
         defer alloc.free(app_support_path);
-        self.loadOptionalFile(alloc, app_support_path);
+        self.loadOptionalFile(alloc, app_support_path, true);
     }
 }
 

src/config/config-template

@@ -0,0 +1,42 @@
+# This is the configuration file for Ghostty.
+#
+# This template file has been automatically created at path
+#   {[path]s} 
+# since Ghostty couldn't find any existing config files on your system.
+#
+# The template does not set any default options, as Ghostty follows
+# a zero-config philosophy: users should only need to manually set a few
+# options, and they should be fully aware of what each option does.
+#
+# Run `ghostty +show-config --default --docs` to view a list of
+# all available config options and their default values.
+# 
+# Additionally, each config option is also explained in detail
+# on Ghostty's website, at https://ghostty.org/docs/config.
+
+# Config syntax crash course
+# ==========================
+# # The config file consists of simple key-value pairs,
+# # separated by equals signs.
+# font-family = Iosevka
+# window-padding-x = 2
+#
+# # Spacing around the equals sign does not matter.
+# # All of these are identical:
+# key=value
+# key= value
+# key =value
+# key = value
+#
+# # Any line beginning with a # is a comment. It's not possible to put
+# # a comment after a config option, since it would be interpreted as a
+# # part of the value. For example, this will have a value of "#123abc":
+# background = #123abc
+#
+# # Empty values are used to reset config keys to default.
+# key =
+#
+# # Some config options have unique syntaxes for their value,
+# # which is explained in the docs for that config option.
+# # Just for example:
+# resize-overlay-duration = 4s 200ms