core: document which release added config entries (#7859)

For each config entry, add a comment specifying in which release it was
first added. In some cases I note when certain aspects of each config
entry were modified.

src/config/Config.zig

@@ -305,6 +305,7 @@ pub const compatibility = std.StaticStringMap(
 ///
 ///   * `cursor` - Break runs under the cursor.
 ///
+/// Available since: 1.2.0
 @"font-shaping-break": FontShapingBreak = .{},
 
 /// What color space to use when performing alpha blending.
@@ -329,6 +330,8 @@ pub const compatibility = std.StaticStringMap(
 /// * `linear-corrected` - Same as `linear`, but with a correction step applied
 ///   for text that makes it look nearly or completely identical to `native`,
 ///   but without any of the darkening artifacts.
+///
+/// Available since: 1.1.0
 @"alpha-blending": AlphaBlending =
     if (builtin.os.tag == .macos)
         .native
@@ -407,6 +410,8 @@ pub const compatibility = std.StaticStringMap(
 /// roughly the same height as capital letters.
 ///
 /// See the notes about adjustments in `adjust-cell-width`.
+///
+/// Available in: 1.2.0
 @"adjust-icon-height": ?MetricModifier = null,
 
 /// The method to use for calculating the cell width of a grapheme cluster.
@@ -515,7 +520,6 @@ pub const compatibility = std.StaticStringMap(
 /// be fixed in a future update:
 ///
 ///   - macOS: titlebar tabs style is not updated when switching themes.
-///
 theme: ?Theme = null,
 
 /// Background color for the window.
@@ -539,6 +543,8 @@ foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF },
 /// For sufficiently large images, this could lead to a large increase in
 /// memory usage (specifically VRAM usage). A future Ghostty improvement
 /// will resolve this by sharing image textures across terminals.
+///
+/// Available since: 1.2.0
 @"background-image": ?Path = null,
 
 /// Background image opacity.
@@ -558,6 +564,8 @@ foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF },
 /// configured `background-opacity` is `0.5` and `background-image-opacity`
 /// is set to `1.5`, then the final opacity of the background image will be
 /// `0.5 * 1.5 = 0.75`.
+///
+/// Available since: 1.2.0
 @"background-image-opacity": f32 = 1.0,
 
 /// Background image position.
@@ -574,6 +582,8 @@ foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF },
 ///   * `bottom-right`
 ///
 /// The default value is `center`.
+///
+/// Available since: 1.2.0
 @"background-image-position": BackgroundImagePosition = .center,
 
 /// Background image fit.
@@ -602,6 +612,8 @@ foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF },
 ///     Don't scale the background image.
 ///
 /// The default value is `contain`.
+///
+/// Available since: 1.2.0
 @"background-image-fit": BackgroundImageFit = .contain,
 
 /// Whether to repeat the background image or not.
@@ -611,6 +623,8 @@ foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF },
 /// fill the terminal area.
 ///
 /// The default value is `false`.
+///
+/// Available since: 1.2.0
 @"background-image-repeat": bool = false,
 
 /// The foreground and background color for selection. If this is not set, then
@@ -636,6 +650,8 @@ foreground: Color = .{ .r = 0xFF, .g = 0xFF, .b = 0xFF },
 ///
 /// If this is `false`, then the selection can still be manually
 /// cleared by clicking once or by pressing `escape`.
+///
+/// Available since: 1.2.0
 @"selection-clear-on-typing": bool = true,
 
 /// The minimum contrast ratio between the foreground and background colors.
@@ -677,7 +693,6 @@ palette: Palette = .{},
 ///
 ///   * `cell-background` - Match the cell background color.
 ///     (Available since version 1.2.0)
-///
 @"cursor-color": ?TerminalColor = null,
 
 /// The opacity level (opposite of transparency) of the cursor. A value of 1
@@ -702,7 +717,6 @@ palette: Palette = .{},
 ///   * `bar`
 ///   * `underline`
 ///   * `block_hollow`
-///
 @"cursor-style": terminal.CursorStyle = .block,
 
 /// Sets the default blinking state of the cursor. This is just the default
@@ -722,7 +736,6 @@ palette: Palette = .{},
 ///   * ` ` (blank)
 ///   * `true`
 ///   * `false`
-///
 @"cursor-style-blink": ?bool = null,
 
 /// The color of the text under the cursor. If this is not set, a default will
@@ -779,7 +792,6 @@ palette: Palette = .{},
 ///   * `false`
 ///   * `always`
 ///   * `never`
-///
 @"mouse-shift-capture": MouseShiftCapture = .false,
 
 /// Multiplier for scrolling distance with the mouse wheel. Any value less
@@ -787,6 +799,8 @@ palette: Palette = .{},
 /// value.
 ///
 /// A value of "3" (default) scrolls 3 lines per tick.
+///
+/// Available since: 1.2.0
 @"mouse-scroll-multiplier": f64 = 3.0,
 
 /// The opacity level (opposite of transparency) of the background. A value of
@@ -855,6 +869,8 @@ palette: Palette = .{},
 
 /// The color of the split divider. If this is not set, a default will be chosen.
 /// Specified as either hex (`#RRGGBB` or `RRGGBB`) or a named X11 color.
+///
+/// Available since: 1.1.0
 @"split-divider-color": ?Color = null,
 
 /// The command to run, usually a shell. If this is not an absolute path, it'll
@@ -869,14 +885,14 @@ palette: Palette = .{},
 /// arguments are provided, the command will be executed using `/bin/sh -c`
 /// to offload shell argument expansion.
 ///
-/// To avoid shell expansion altogether, prefix the command with `direct:`,
+/// To avoid shell expansion altogether, prefix the command with `direct:`, e.g.
-/// e.g. `direct:nvim foo`. This will avoid the roundtrip to `/bin/sh` but will
+/// `direct:nvim foo`. This will avoid the roundtrip to `/bin/sh` but will also
-/// also not support any shell parsing such as arguments with spaces, filepaths
+/// not support any shell parsing such as arguments with spaces, filepaths with
-/// with `~`, globs, etc.
+/// `~`, globs, etc. (Available since: 1.2.0)
 ///
-/// You can also explicitly prefix the command with `shell:` to always
+/// You can also explicitly prefix the command with `shell:` to always wrap the
-/// wrap the command in a shell. This can be used to ensure our heuristics
+/// command in a shell. This can be used to ensure our heuristics to choose the
-/// to choose the right mode are not used in case they are wrong.
+/// right mode are not used in case they are wrong. (Available since: 1.2.0)
 ///
 /// This command will be used for all new terminal surfaces, i.e. new windows,
 /// tabs, etc. If you want to run a command only for the first terminal surface
@@ -922,7 +938,6 @@ command: ?Command = null,
 ///     shell integration with a `-e`-executed command, you must either
 ///     name your binary appropriately or source the shell integration script
 ///     manually.
-///
 @"initial-command": ?Command = null,
 
 /// Extra environment variables to pass to commands launched in a terminal
@@ -959,6 +974,8 @@ command: ?Command = null,
 /// These environment variables _will not_ be passed to commands run by Ghostty
 /// for other purposes, like `open` or `xdg-open` used to open URLs in your
 /// browser.
+///
+/// Available since: 1.2.0
 env: RepeatableStringMap = .{},
 
 /// Data to send as input to the command on startup.
@@ -1000,6 +1017,8 @@ env: RepeatableStringMap = .{},
 ///
 /// Changing this configuration at runtime will only affect new
 /// terminals.
+///
+/// Available since: 1.2.0
 input: RepeatableReadableIO = .{},
 
 /// If true, keep the terminal open after the command exits. Normally, the
@@ -1068,11 +1087,15 @@ link: RepeatableLink = .{},
 /// previews are never shown. When set to "osc8", link previews are only shown
 /// for hyperlinks created with the OSC 8 sequence (in this case, the link text
 /// can differ from the link destination).
+///
+/// Available since: 1.2.0
 @"link-previews": LinkPreviews = .true,
 
 /// Whether to start the window in a maximized state. This setting applies
 /// to new windows and does not apply to tabs, splits, etc. However, this setting
 /// will apply to all new windows, not just the first one.
+///
+/// Available since: 1.1.0
 maximize: bool = false,
 
 /// Start new windows in fullscreen. This setting applies to new windows and
@@ -1297,6 +1320,8 @@ class: ?[:0]const u8 = null,
 ///     applies to actions that are surface-specific. For actions that
 ///     are already global (e.g. `quit`), this prefix has no effect.
 ///
+///     Available since: 1.0.0
+///
 ///   * `global:` - Make the keybind global. By default, keybinds only work
 ///     within Ghostty and under the right conditions (application focused,
 ///     sometimes terminal focused, etc.). If you want a keybind to work
@@ -1305,6 +1330,9 @@ class: ?[:0]const u8 = null,
 ///     work in all environments; see the additional notes below for more
 ///     information.
 ///
+///     Available since: 1.0.0 (on macOS)
+///     Available since: 1.2.0 (on GTK)
+///
 ///   * `unconsumed:` - Do not consume the input. By default, a keybind
 ///     will consume the input, meaning that the associated encoding (if
 ///     any) will not be sent to the running program in the terminal. If
@@ -1315,6 +1343,8 @@ class: ?[:0]const u8 = null,
 ///     Since they are not associated with a specific terminal surface,
 ///     they're never encoded.
 ///
+///     Available since: 1.0.0
+///
 ///   * `performable:` - Only consume the input if the action is able to be
 ///     performed. For example, the `copy_to_clipboard` action will only
 ///     consume the input if there is a selection to copy. If there is no
@@ -1330,6 +1360,8 @@ class: ?[:0]const u8 = null,
 ///     Performable keybinds will still work, they just won't appear as
 ///     a shortcut label in the menu.
 ///
+///     Available since: 1.1.0
+///
 /// Keybind triggers are not unique per prefix combination. For example,
 /// `ctrl+a` and `global:ctrl+a` are not two separate keybinds. The keybind
 /// set later will overwrite the keybind set earlier. In this case, the
@@ -1439,7 +1471,6 @@ keybind: Keybinds = .{},
 ///   do not look good extended.
 /// * The nearest row contains a perfect fit powerline character. These
 ///   don't look good extended.
-///
 @"window-padding-color": WindowPaddingColor = .background,
 
 /// Synchronize rendering with the screen refresh rate. If true, this will
@@ -1486,6 +1517,8 @@ keybind: Keybinds = .{},
 ///
 ///   * `client` - Prefer client-side decorations.
 ///
+///     Available since: 1.1.0
+///
 ///   * `server` - Prefer server-side decorations. This is only relevant
 ///     on Linux with GTK, either on X11, or Wayland on a compositor that
 ///     supports the `org_kde_kwin_server_decoration` protocol (e.g. KDE Plasma,
@@ -1494,6 +1527,8 @@ keybind: Keybinds = .{},
 ///     If `server` is set but the environment doesn't support server-side
 ///     decorations, client-side decorations will be used instead.
 ///
+///     Available since: 1.1.0
+///
 /// The default value is `auto`.
 ///
 /// For the sake of backwards compatibility and convenience, this setting also
@@ -1516,6 +1551,8 @@ keybind: Keybinds = .{},
 ///
 /// Note: any font available on the system may be used, this font is not
 /// required to be a fixed-width font.
+///
+/// Available since: 1.1.0 (on GTK)
 @"window-title-font-family": ?[:0]const u8 = null,
 
 /// The text that will be displayed in the subtitle of the window. Valid values:
@@ -1525,6 +1562,8 @@ keybind: Keybinds = .{},
 ///      surface.
 ///
 /// This feature is only supported on GTK.
+///
+/// Available since: 1.1.0
 @"window-subtitle": WindowSubtitle = .false,
 
 /// The theme to use for the windows. Valid values:
@@ -1668,6 +1707,8 @@ keybind: Keybinds = .{},
 ///
 ///    Always display the tab bar, even when there's only one tab.
 ///
+///    Available since: 1.2.0
+///
 ///  - `auto` *(default)*
 ///
 ///    Automatically show and hide the tab bar. The tab bar is only
@@ -1752,6 +1793,8 @@ keybind: Keybinds = .{},
 ///
 /// The maximum value is `584y 49w 23h 34m 33s 709ms 551µs 615ns`. Any
 /// value larger than this will be clamped to the maximum value.
+///
+/// Available since 1.0.0
 @"resize-overlay-duration": Duration = .{ .duration = 750 * std.time.ns_per_ms },
 
 /// If true, when there are multiple split panes, the mouse selects the pane
@@ -1797,6 +1840,8 @@ keybind: Keybinds = .{},
 /// Warning: This can expose sensitive information at best and enable
 /// arbitrary code execution at worst (with a maliciously crafted title
 /// and a minor amount of user interaction).
+///
+/// Available since: 1.0.1
 @"title-report": bool = false,
 
 /// The total amount of bytes that can be used for image data (e.g. the Kitty
@@ -1984,6 +2029,8 @@ keybind: Keybinds = .{},
 /// This configuration is only supported on macOS. Linux doesn't
 /// support undo operations at all so this configuration has no
 /// effect.
+///
+/// Available since: 1.2.0
 @"undo-timeout": Duration = .{ .duration = 5 * std.time.ns_per_s },
 
 /// The position of the "quick" terminal window. To learn more about the
@@ -2087,6 +2134,8 @@ keybind: Keybinds = .{},
 ///
 /// Only implemented on macOS.
 /// On Linux the behavior is always equivalent to `move`.
+///
+/// Available since: 1.1.0
 @"quick-terminal-space-behavior": QuickTerminalSpaceBehavior = .move,
 
 /// Determines under which circumstances that the quick terminal should receive
@@ -2115,6 +2164,8 @@ keybind: Keybinds = .{},
 ///
 /// Only has an effect on Linux Wayland.
 /// On macOS the behavior is always equivalent to `on-demand`.
+///
+/// Available since: 1.2.0
 @"quick-terminal-keyboard-interactivity": QuickTerminalKeyboardInteractivity = .@"on-demand",
 
 /// Whether to enable shell integration auto-injection or not. Shell integration
@@ -2182,6 +2233,8 @@ keybind: Keybinds = .{},
 /// ```ini
 /// command-palette-entry =
 /// ```
+///
+/// Available since: 1.2.0
 @"command-palette-entry": RepeatableCommand = .{},
 
 /// Sets the reporting format for OSC sequences that request color information.
@@ -2346,6 +2399,8 @@ keybind: Keybinds = .{},
 ///    Only implemented on macOS.
 ///
 /// Example: `audio`, `no-audio`, `system`, `no-system`
+///
+/// Available since: 1.2.0
 @"bell-features": BellFeatures = .{},
 
 /// If `audio` is an enabled bell feature, this is a path to an audio file. If
@@ -2353,12 +2408,16 @@ keybind: Keybinds = .{},
 /// configuration file that it is referenced from, or from the current working
 /// directory if this is used as a CLI flag. The path may be prefixed with `~/`
 /// to reference the user's home directory. (GTK only)
+///
+/// Available since: 1.2.0
 @"bell-audio-path": ?Path = null,
 
 /// If `audio` is an enabled bell feature, this is the volume to play the audio
 /// file at (relative to the system volume). This is a floating point number
 /// ranging from 0.0 (silence) to 1.0 (as loud as possible). The default is 0.5.
 /// (GTK only)
+///
+/// Available since: 1.2.0
 @"bell-audio-volume": f64 = 0.5,
 
 /// Control the in-app notifications that Ghostty shows.
@@ -2384,6 +2443,8 @@ keybind: Keybinds = .{},
 /// enable all notifications.
 ///
 /// This configuration only applies to GTK.
+///
+/// Available since: 1.1.0
 @"app-notifications": AppNotifications = .{},
 
 /// If anything other than false, fullscreen mode on macOS will not use the
@@ -2434,6 +2495,8 @@ keybind: Keybinds = .{},
 /// The default value is `visible`.
 ///
 /// Changing this option at runtime only applies to new windows.
+///
+/// Available since: 1.2.0
 @"macos-window-buttons": MacWindowButtons = .visible,
 
 /// The style of the macOS titlebar. Available values are: "native",
@@ -2556,6 +2619,8 @@ keybind: Keybinds = .{},
 ///
 /// Note: When the macOS application is hidden, keyboard layout changes
 /// will no longer be automatic. This is a limitation of macOS.
+///
+/// Available since: 1.2.0
 @"macos-hidden": MacHidden = .never,
 
 /// If true, Ghostty on macOS will automatically enable the "Secure Input"
@@ -2617,7 +2682,6 @@ keybind: Keybinds = .{},
 ///     This is because the update dialog is managed through a
 ///     separate framework and cannot be customized without significant
 ///     effort.
-///
 @"macos-icon": MacAppIcon = .official,
 
 /// The material to use for the frame of the macOS app icon.
@@ -2631,7 +2695,6 @@ keybind: Keybinds = .{},
 ///
 /// Note: This configuration is required when `macos-icon` is set to
 /// `custom-style`.
-///
 @"macos-icon-frame": MacAppIconFrame = .aluminum,
 
 /// The color of the ghost in the macOS app icon.
@@ -2652,7 +2715,6 @@ keybind: Keybinds = .{},
 ///
 /// Note: This configuration is required when `macos-icon` is set to
 /// `custom-style`.
-///
 @"macos-icon-screen-color": ?ColorList = null,
 
 /// Whether macOS Shortcuts are allowed to control Ghostty.
@@ -2676,6 +2738,7 @@ keybind: Keybinds = .{},
 ///
 /// * `deny` - Deny Shortcuts from controlling Ghostty.
 ///
+/// Available since: 1.2.0
 @"macos-shortcuts": MacShortcuts = .ask,
 
 /// Put every surface (tab, split, window) into a dedicated Linux cgroup.
@@ -2703,7 +2766,6 @@ keybind: Keybinds = .{},
 ///   * `always` - Always use cgroups.
 ///   * `single-instance` - Enable cgroups only for Ghostty instances launched
 ///     as single-instance applications (see gtk-single-instance).
-///
 @"linux-cgroup": LinuxCgroup = if (builtin.os.tag == .linux)
     .@"single-instance"
 else
@@ -2740,6 +2802,8 @@ else
 
 /// Enable or disable GTK's OpenGL debugging logs. The default is `true` for
 /// debug builds, `false` for all others.
+///
+/// Available since: 1.1.0
 @"gtk-opengl-debug": bool = builtin.mode == .Debug,
 
 /// If `true`, the Ghostty GTK application will run in single-instance mode:
@@ -2777,6 +2841,8 @@ else
 
 /// If this is `true`, the titlebar will be hidden when the window is maximized,
 /// and shown when the titlebar is unmaximized. GTK only.
+///
+/// Available since: 1.1.0
 @"gtk-titlebar-hide-when-maximized": bool = false,
 
 /// Determines the appearance of the top and bottom bars tab bar.
@@ -2814,6 +2880,8 @@ else
 /// not exist. If you want to include a file that begins with a literal ?
 /// character, surround the file path in double quotes (").
 /// The file size limit for a single stylesheet is 5MiB.
+///
+/// Available since: 1.1.0
 @"gtk-custom-css": RepeatablePath = .{},
 
 /// If `true` (default), applications running in the terminal can show desktop
@@ -2866,6 +2934,8 @@ term: []const u8 = "xterm-ghostty",
 /// this isn't intended to be modified by users, the documentation is
 /// lighter than the other configurations and users are expected to
 /// refer to the code for details.
+///
+/// Available since: 1.2.0
 @"launched-from": ?LaunchSource = null,
 
 /// Configures the low-level API to use for async IO, eventing, etc.
@@ -2894,6 +2964,8 @@ term: []const u8 = "xterm-ghostty",
 ///
 /// This is only supported on Linux, since this is the only platform
 /// where we have multiple options. On macOS, we always use `kqueue`.
+///
+/// Available since: 1.2.0
 @"async-backend": AsyncBackend = .auto,
 
 /// Control the auto-update functionality of Ghostty. This is only supported