mirror of
https://github.com/ghostty-org/ghostty.git
synced 2025-07-14 15:56:13 +03:00
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.
This commit is contained in:
Mitchell Hashimoto
@ -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:`,
|
||||
/// e.g. `direct:nvim foo`. This will avoid the roundtrip to `/bin/sh` but will
|
||||
/// also not support any shell parsing such as arguments with spaces, filepaths
|
||||
/// with `~`, globs, etc.
|
||||
/// To avoid shell expansion altogether, prefix the command with `direct:`, e.g.
|
||||
/// `direct:nvim foo`. This will avoid the roundtrip to `/bin/sh` but will also
|
||||
/// not support any shell parsing such as arguments with spaces, filepaths with
|
||||
/// `~`, globs, etc. (Available since: 1.2.0)
|
||||
///
|
||||
/// You can also explicitly prefix the command with `shell:` to always
|
||||
/// wrap the command in a shell. This can be used to ensure our heuristics
|
||||
/// to choose the right mode are not used in case they are wrong.
|
||||
/// You can also explicitly prefix the command with `shell:` to always wrap the
|
||||
/// command in a shell. This can be used to ensure our heuristics to choose the
|
||||
/// 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
|
||||
|
||||
Reference in New Issue
Block a user