mirrors/ghostty
1
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2025-09-05 19:08:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

core: document keybind actions better

Browse Source 
The current documentation for actions are very sparse and would leave
someone (even including contributors) as to what exactly they do.
On top of that there are many stylistic and grammatical problems that are
simply no longer in line with our current standards, and certainly not
on par with our configuration options reference.

Hence, I've taken it upon myself to add, clarify, supplement, edit and
even rewrite the documentation for most of these actions, in a wider
effort of trying to offer better, clearer documentation for our users.
This commit is contained in:
Leah Amelia Chen
2025-06-04 15:07:58 +02:00
parent 1ff9162598
commit 2c8d6ba944
2 changed files with 285 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

427
src/input/Binding.zig
View File

@@ -222,114 +222,191 @@ pub fn lessThan(_: void, lhs: Binding, rhs: Binding) bool {
/// The set of actions that a keybinding can take.
pub const Action = union(enum) {
/// Ignore this key combination, don't send it to the child process,
/// pretend that it never happened at the Ghostty level. The key
/// combination may still be processed by the OS or other
/// applications.
/// Ignore this key combination.
///
/// Ghostty will not process this combination nor forward it to the child
/// process within the terminal, but it may still be processed by the OS or
/// other applications.
ignore,
/// This action is used to flag that the binding should be removed from
/// the set. This should never exist in an active set and `set.put` has an
/// assertion to verify this.
/// Unbind a previously bound key binding.
///
/// This is only able to unbind bindings that were previously
/// bound to Ghostty. This cannot unbind bindings that were not
/// bound by Ghostty (e.g. bindings set by the OS or some other
/// application).
/// This cannot unbind bindings that were not bound by Ghostty or the user
/// (e.g. bindings set by the OS or some other application).
unbind,
/// Send a CSI sequence. The value should be the CSI sequence without the
/// CSI header (`ESC [` or `\x1b[`).
/// Send a CSI sequence.
///
/// The value should be the CSI sequence without the CSI header (`ESC [` or
/// `\x1b[`).
///
/// For example, `csi:0m` can be sent to reset all styles of the current text.
csi: []const u8,
/// Send an `ESC` sequence.
esc: []const u8,
/// Send the given text. Uses Zig string literal syntax. This is currently
/// not validated. If the text is invalid (i.e. contains an invalid escape
/// sequence), the error will currently only show up in logs.
/// Send the specified text.
///
/// Uses Zig string literal syntax. This is currently not validated.
/// If the text is invalid (i.e. contains an invalid escape sequence),
/// the error will currently only show up in logs.
text: []const u8,
/// Send data to the pty depending on whether cursor key mode is enabled
/// (`application`) or disabled (`normal`).
cursor_key: CursorKey,
/// Reset the terminal. This can fix a lot of issues when a running
/// program puts the terminal into a broken state. This is equivalent to
/// when you type "reset" and press enter.
/// Reset the terminal.
///
/// This can fix a lot of issues when a running program puts the terminal
/// into a broken state, equivalent to running the `reset` command.
///
/// If you do this while in a TUI program such as vim, this may break
/// the program. If you do this while in a shell, you may have to press
/// enter after to get a new prompt.
reset,
/// Copy and paste.
/// Copy the selected text to the clipboard.
copy_to_clipboard,
/// Paste the contents of the default clipboard.
paste_from_clipboard,
/// Paste the contents of the selection clipboard.
paste_from_selection,
/// Copy the URL under the cursor to the clipboard. If there is no
/// URL under the cursor, this does nothing.
/// If there is a URL under the cursor, copy it to the default clipboard.
copy_url_to_clipboard,
/// Increase/decrease the font size by a certain amount.
/// Increase the font size by the specified amount in points (pt).
///
/// For example, `increase_font_size:1.5` will increase the font size
/// by 1.5 points.
increase_font_size: f32,
/// Decrease the font size by the specified amount in points (pt).
///
/// For example, `decrease_font_size:1.5` will decrease the font size
/// by 1.5 points.
decrease_font_size: f32,
/// Reset the font size to the original configured size.
reset_font_size,
/// Clear the screen. This also clears all scrollback.
/// Clear the screen and all scrollback.
clear_screen,
/// Select all text on the screen.
select_all,
/// Scroll the screen varying amounts.
/// Scroll to the top of the screen.
scroll_to_top,
/// Scroll to the bottom of the screen.
scroll_to_bottom,
/// Scroll to the selected text.
scroll_to_selection,
/// Scroll the screen up by one page.
scroll_page_up,
/// Scroll the screen down by one page.
scroll_page_down,
/// Scroll the screen by the specified fraction of a page.
///
/// Positive values scroll downwards, and negative values scroll upwards.
///
/// For example, `scroll_page_fractional:0.5` would scroll the screen
/// downwards by half a page, while `scroll_page_fractional:-1.5` would
/// scroll it upwards by one and a half pages.
scroll_page_fractional: f32,
/// Scroll the screen by the specified amount of lines.
///
/// Positive values scroll downwards, and negative values scroll upwards.
///
/// For example, `scroll_page_lines:3` would scroll the screen downwards
/// by 3 lines, while `scroll_page_lines:-10` would scroll it upwards by 10
/// lines.
scroll_page_lines: i16,
/// Adjust the current selection in a given direction. Does nothing if no
/// selection exists.
/// Adjust the current selection in the given direction or position,
/// relative to the cursor.
///
/// Arguments:
/// - left, right, up, down, page_up, page_down, home, end,
/// beginning_of_line, end_of_line
/// WARNING: This does not create a new selection, and does nothing when
/// there currently isn't one.
///
/// Valid arguments are:
///
/// - `left`, `right`
///
/// Adjust the selection one cell to the left or right respectively.
///
/// - `up`, `down`
///
/// Adjust the selection one line upwards or downwards respectively.
///
/// - `page_up`, `page_down`
///
/// Adjust the selection one page upwards or downwards respectively.
///
/// - `home`, `end`
///
/// Adjust the selection to the top-left or the bottom-right corner
/// of the screen respectively.
///
/// - `beginning_of_line`, `end_of_line`
///
/// Adjust the selection to the beginning or the end of the line
/// respectively.
///
/// Example: Extend selection to the right
/// keybind = shift+right=adjust_selection:right
adjust_selection: AdjustSelection,
/// Jump the viewport forward or back by prompt. Positive number is the
/// number of prompts to jump forward, negative is backwards.
/// Jump the viewport forward or back by the given number of prompts.
///
/// Requires shell integration.
///
/// Positive values scroll downwards, and negative values scroll upwards.
jump_to_prompt: i16,
/// Write the entire scrollback into a temporary file. The action
/// determines what to do with the filepath. Valid values are:
/// Write the entire scrollback into a temporary file with the specified
/// action. The action determines what to do with the filepath.
///
/// Valid actions are:
///
/// - `paste`
///
/// Paste the file path into the terminal.
///
/// - `open`
///
/// Open the file in the default OS editor for text files.
///
/// - "paste": Paste the file path into the terminal.
/// - "open": Open the file in the default OS editor for text files.
/// The default OS editor is determined by using `open` on macOS
/// and `xdg-open` on Linux.
///
write_scrollback_file: WriteScreenAction,
/// Same as write_scrollback_file but writes the full screen contents.
/// See write_scrollback_file for available values.
/// Write the contents of the screen into a temporary file with the
/// specified action.
///
/// See `write_scrollback_file` for possible actions.
write_screen_file: WriteScreenAction,
/// Same as write_scrollback_file but writes the selected text.
/// If there is no selected text this does nothing (it doesn't
/// even create an empty file). See write_scrollback_file for
/// available values.
/// Write the currently selected text into a temporary file with the
/// specified action.
///
/// See `write_scrollback_file` for possible actions.
///
/// Does nothing when no text is selected.
write_selection_file: WriteScreenAction,
/// Open a new window. If the application isn't currently focused,
/// Open a new window.
///
/// If the application isn't currently focused,
/// this will bring it to the front.
new_window,
@@ -342,190 +419,246 @@ pub const Action = union(enum) {
/// Go to the next tab.
next_tab,
/// Go to the last tab (the one with the highest index)
/// Go to the last tab.
last_tab,
/// Go to the tab with the specific number, 1-indexed. If the tab number
/// is higher than the number of tabs, this will go to the last tab.
/// Go to the tab with the specific index, starting from 1.
///
/// If the tab number is higher than the number of tabs,
/// this will go to the last tab.
goto_tab: usize,
/// Moves a tab by a relative offset.
/// Adjusts the tab position based on `offset`. For example `move_tab:-1` for left, `move_tab:1` for right.
/// If the new position is out of bounds, it wraps around cyclically within the tab range.
///
/// Positive values move the tab forwards, and negative values move it
/// backwards. If the new position is out of bounds, it is wrapped around
/// cyclically within the tab list.
///
/// For example, `move_tab:1` moves the tab one position forwards, and if
/// it was already the last tab in the list, it wraps around and becomes
/// the first tab in the list. Likewise, `move_tab:-1` moves the tab one
/// position backwards, and if it was the first tab, then it will become
/// the last tab.
move_tab: isize,
/// Toggle the tab overview.
/// This only works with libadwaita version 1.4.0 or newer.
///
/// This is only supported on Linux and when the system's libadwaita
/// version is 1.4 or newer. The current libadwaita version can be
/// found by running `ghostty +version`.
toggle_tab_overview,
/// Change the title of the current focused surface via a prompt.
/// Change the title of the current focused surface via a pop-up prompt.
///
/// This requires libadwaita 1.5 or newer on Linux. The current libadwaita
/// version can be found by running `ghostty +version`.
prompt_surface_title,
/// Create a new split in the given direction.
/// Create a new split in the specified direction.
///
/// Arguments:
/// - right, down, left, up, auto (splits along the larger direction)
/// Valid arguments:
///
/// - `right`, `down`, `left`, `up`
///
/// Creates a new split in the corresponding direction.
///
/// - `auto`
///
/// Creates a new split along the larger direction.
/// For example, if the parent split is currently wider than it is tall,
/// then a left-right split would be created, and vice versa.
///
/// Example: Create split on the right
/// keybind = cmd+shift+d=new_split:right
new_split: SplitDirection,
/// Focus on a split in a given direction. For example `goto_split:up`.
/// Valid values are left, right, up, down, previous and next.
/// Focus on a split either in the specified direction (`right`, `down`,
/// `left` and `up`), or in the adjacent split in the order of creation
/// (`previous` and `next`).
goto_split: SplitFocusDirection,
/// zoom/unzoom the current split.
/// Zoom in or out of the current split.
///
/// When a split is zoomed into, it will take up the entire space in
/// the current tab, hiding other splits. The tab or tab bar would also
/// reflect this by displaying an icon indicating the zoomed state.
toggle_split_zoom,
/// Resize the current split in a given direction.
///
/// Arguments:
/// - up, down, left, right
/// - the number of pixels to resize the split by
///
/// Example: Move divider up 10 pixels
/// keybind = cmd+shift+up=resize_split:up,10
/// Resize the current split in the specified direction and amount in
/// pixels. The two arguments should be joined with a comma (`,`),
/// like in `resize_split:up,10`.
resize_split: SplitResizeParameter,
/// Equalize all splits in the current window
/// Equalize the size of all splits in the current window.
equalize_splits,
/// Reset the window to the default size. The "default size" is the
/// size that a new window would be created with. This has no effect
/// if the window is fullscreen.
///
/// Only implemented on macOS.
reset_window_size,
/// Control the terminal inspector visibility.
/// Control the visibility of the terminal inspector.
///
/// Arguments:
/// - toggle, show, hide
///
/// Example: Toggle inspector visibility
/// keybind = cmd+i=inspector:toggle
/// Valid arguments: `toggle`, `show`, `hide`.
inspector: InspectorMode,
/// Show the GTK inspector.
///
/// Has no effect on macOS.
show_gtk_inspector,
/// Open the configuration file in the default OS editor. If your default OS
/// editor isn't configured then this will fail. Currently, any failures to
/// open the configuration will show up only in the logs.
/// Open the configuration file in the default OS editor.
///
/// If your default OS editor isn't configured then this will fail.
/// Currently, any failures to open the configuration will show up only in
/// the logs.
open_config,
/// Reload the configuration. The exact meaning depends on the app runtime
/// in use but this usually involves re-reading the configuration file
/// and applying any changes. Note that not all changes can be applied at
/// runtime.
/// Reload the configuration.
///
/// The exact meaning depends on the app runtime in use, but this usually
/// involves re-reading the configuration file and applying any changes
/// Note that not all changes can be applied at runtime.
reload_config,
/// Close the current "surface", whether that is a window, tab, split, etc.
/// This only closes ONE surface. This will trigger close confirmation as
/// configured.
///
/// This might trigger a close confirmation popup, depending on the value
/// of the `confirm-close-surface` configuration setting.
close_surface,
/// Close the current tab, regardless of how many splits there may be.
/// This will trigger close confirmation as configured.
/// Close the current tab and all splits therein.
///
/// This might trigger a close confirmation popup, depending on the value
/// of the `confirm-close-surface` configuration setting.
close_tab,
/// Close the window, regardless of how many tabs or splits there may be.
/// This will trigger close confirmation as configured.
/// Close the current window and all tabs and splits therein.
///
/// This might trigger a close confirmation popup, depending on the value
/// of the `confirm-close-surface` configuration setting.
close_window,
/// Close all windows. This will trigger close confirmation as configured.
/// This only works for macOS currently.
/// Close all windows.
///
/// WARNING: This action has been deprecated and has no effect on either
/// Linux or macOS. Users are instead encouraged to use `all:close_window`
/// instead.
close_all_windows,
/// Toggle maximized window state. This only works on Linux.
/// Maximize or unmaximize the current window.
///
/// This has no effect on macOS as it does not have the concept of
/// maximized windows.
toggle_maximize,
/// Toggle fullscreen mode of window.
/// Fullscreen or unfullscreen the current window.
toggle_fullscreen,
/// Toggle window decorations on and off. This only works on Linux.
/// Toggle window decorations (titlebar, buttons, etc.) for the current window.
///
/// Only implemented on Linux.
toggle_window_decorations,
/// Toggle whether the terminal window is always on top of other
/// windows even when it is not focused. Terminal windows always start
/// as normal (not always on top) windows.
/// Toggle whether the terminal window should always float on top of other
/// windows even when unfocused.
///
/// This only works on macOS.
/// Terminal windows always start as normal (not float-on-top) windows.
///
/// Only implemented on macOS.
toggle_window_float_on_top,
/// Toggle secure input mode on or off. This is used to prevent apps
/// that monitor input from seeing what you type. This is useful for
/// entering passwords or other sensitive information.
/// Toggle secure input mode.
///
/// This applies to the entire application, not just the focused
/// terminal. You must toggle it off to disable it, or quit Ghostty.
/// This is used to prevent apps from monitoring your keyboard input
/// when entering passwords or other sensitive information.
///
/// This only works on macOS, since this is a system API on macOS.
/// This applies to the entire application, not just the focused terminal.
/// You must manually untoggle it or quit Ghostty entirely to disable it.
///
/// Only implemented on macOS, as this uses a built-in system API.
toggle_secure_input,
/// Toggle the command palette. The command palette is a UI element
/// that lets you see what actions you can perform, their associated
/// keybindings (if any), a search bar to filter the actions, and
/// the ability to then execute the action.
/// Toggle the command palette.
///
/// The command palette is a popup that lets you see what actions
/// you can perform, their associated keybindings (if any), a search bar
/// to filter the actions, and the ability to then execute the action.
///
/// This requires libadwaita 1.5 or newer on Linux. The current libadwaita
/// version can be found by running `ghostty +version`.
toggle_command_palette,
/// Toggle the "quick" terminal. The quick terminal is a terminal that
/// appears on demand from a keybinding, often sliding in from a screen
/// edge such as the top. This is useful for quick access to a terminal
/// without having to open a new window or tab.
/// Toggle the quick terminal.
///
/// When the quick terminal loses focus, it disappears. The terminal state
/// is preserved between appearances, so you can always press the keybinding
/// to bring it back up.
/// The quick terminal, also known as the "Quake-style" or drop-down
/// terminal, is a terminal window that appears on demand from a keybinding,
/// often sliding in from a screen edge such as the top. This is useful for
/// quick access to a terminal without having to open a new window or tab.
///
/// To enable the quick terminal globally so that Ghostty doesn't
/// have to be focused, prefix your keybind with `global`. Example:
/// The terminal state is preserved between appearances, so showing the
/// quick terminal after it was already hidden would display the same
/// window instead of creating a new one.
///
/// As quick terminals are often useful when other windows are currently
/// focused, they are best used with *global* keybinds. For example, one
/// can define the following key bind to toggle the quick terminal from
/// anywhere within the system by pressing `` Cmd+` ``:
///
/// ```ini
/// keybind = global:cmd+grave_accent=toggle_quick_terminal
/// keybind = global:cmd+backquote=toggle_quick_terminal
/// ```
///
/// The quick terminal has some limitations:
///
/// - It is a singleton; only one instance can exist at a time.
/// - It does not support tabs, but it does support splits.
/// - It will not be restored when the application is restarted
/// (for systems that support window restoration).
/// - It supports fullscreen, but fullscreen will always be a non-native
/// fullscreen (macos-non-native-fullscreen = true). This only applies
/// to the quick terminal window. This is a requirement due to how
/// the quick terminal is rendered.
/// - Only one quick terminal instance can exist at a time.
///
/// - Unlike normal terminal windows, the quick terminal will not be
/// restored when the application is restarted on systems that support
/// window restoration like macOS.
///
/// - On Linux, the quick terminal is only supported on Wayland and not
/// X11, and only on Wayland compositors that support the `wlr-layer-shell-v1`
/// protocol. In practice, this means that only GNOME users would not be
/// able to use this feature.
///
/// - On Linux, slide-in animations are only supported on KDE, and when
/// the "Sliding Popups" KWin plugin is enabled.
///
/// If you do not have this plugin enabled, open System Settings > Apps
/// & Windows > Window Management > Desktop Effects, and enable the
/// plugin in the plugin list. Ghostty would then need to be restarted
/// fully for this to take effect.
///
/// - Quick terminal tabs are only supported on Linux and not on macOS.
/// This is because tabs on macOS require a title bar.
///
/// - On macOS, a fullscreened quick terminal will always be in non-native
/// fullscreen mode. This is a requirement due to how the quick terminal
/// is rendered.
///
/// See the various configurations for the quick terminal in the
/// configuration file to customize its behavior.
///
/// Supported on macOS and some desktop environments on Linux, namely
/// those that support the `wlr-layer-shell` Wayland protocol
/// (i.e. most desktop environments and window managers except GNOME).
///
/// Slide-in animations on Linux are only supported on KDE when the
/// "Sliding Popups" KWin plugin is enabled. If you do not have this
/// plugin enabled, open System Settings > Apps & Windows > Window
/// Management > Desktop Effects, and enable the plugin in the plugin list.
/// Ghostty would then need to be restarted for this to take effect.
toggle_quick_terminal,
/// Show/hide all windows. If all windows become shown, we also ensure
/// Show or hide all windows. If all windows become shown, we also ensure
/// Ghostty becomes focused. When hiding all windows, focus is yielded
/// to the next application as determined by the OS.
///
/// Note: When the focused surface is fullscreen, this method does nothing.
///
/// This currently only works on macOS.
/// Only implemented on macOS.
toggle_visibility,
/// Check for updates.
///
/// This currently only works on macOS.
/// Only implemented on macOS.
check_for_updates,
/// Quit ghostty.
/// Quit Ghostty.
quit,
/// Crash ghostty in the desired thread for the focused surface.
/// Crash Ghostty in the desired thread for the focused surface.
///
/// WARNING: This is a hard crash (panic) and data can be lost.
///
@@ -535,9 +668,17 @@ pub const Action = union(enum) {
///
/// The value determines the crash location:
///
/// - "main" - crash on the main (GUI) thread.
/// - "io" - crash on the IO thread for the focused surface.
/// - "render" - crash on the render thread for the focused surface.
/// - `main`
///
/// Crash on the main (GUI) thread.
///
/// - `io`
///
/// Crash on the IO thread for the focused surface.
///
/// - `render`
///
/// Crash on the render thread for the focused surface.
///
crash: CrashThread,

2
src/input/command.zig
View File

@@ -119,7 +119,7 @@ fn actionCommands(action: Action.Key) []const Command {
.paste_from_clipboard => comptime &.{.{
.action = .paste_from_clipboard,
.title = "Paste from Clipboard",
.description = "Paste the contents of the clipboard.",
.description = "Paste the contents of the main clipboard.",
}},
.paste_from_selection => comptime &.{.{