Fixes https://github.com/ghostty-org/ghostty/issues/4958
## Changes
1. Fixed documentation generation in `actions.mdx`:
- Fixed an issue where the last action's documentation was [not properly
generated](fe6c69263c/docs/config/keybind/reference.mdx (crash))
- Ensured all actions' documentation is correctly included in the output
2. Improved `ghostty +list-actions --docs` command output formatting:
- Grouped related actions together with shared documentation
- Added proper spacing between action groups
<details>
<summary>ghostty-dev +list-actions --docs</summary>
```
ignore:
Ignore this key combination, don't send it to the child process, just
black hole it.
unbind:
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.
csi:
Send a CSI sequence. The value should be the CSI sequence without the
CSI header (`ESC [` or `\x1b[`).
esc:
Send an `ESC` sequence.
text:
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.
cursor_key:
Send data to the pty depending on whether cursor key mode is enabled
(`application`) or disabled (`normal`).
reset:
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.
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.
copy_to_clipboard:
paste_from_clipboard:
paste_from_selection:
Copy and paste.
copy_url_to_clipboard:
Copy the URL under the cursor to the clipboard. If there is no
URL under the cursor, this does nothing.
increase_font_size:
decrease_font_size:
Increase/decrease the font size by a certain amount.
reset_font_size:
Reset the font size to the original configured size.
clear_screen:
Clear the screen. This also clears all scrollback.
select_all:
Select all text on the screen.
scroll_to_top:
scroll_to_bottom:
scroll_page_up:
scroll_page_down:
scroll_page_fractional:
scroll_page_lines:
Scroll the screen varying amounts.
adjust_selection:
Adjust an existing selection in a given direction. This action
does nothing if there is no active selection.
jump_to_prompt:
Jump the viewport forward or back by prompt. Positive number is the
number of prompts to jump forward, negative is backwards.
write_scrollback_file:
Write the entire scrollback into a temporary file. The action
determines what to do with the filepath. Valid values are:
- "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_screen_file:
Same as write_scrollback_file but writes the full screen contents.
See write_scrollback_file for available values.
write_selection_file:
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.
new_window:
Open a new window. If the application isn't currently focused,
this will bring it to the front.
new_tab:
Open a new tab.
previous_tab:
Go to the previous tab.
next_tab:
Go to the next tab.
last_tab:
Go to the last tab (the one with the highest index)
goto_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.
move_tab:
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.
toggle_tab_overview:
Toggle the tab overview.
This only works with libadwaita enabled currently.
new_split:
Create a new split in the given direction. The new split will appear in
the direction given. For example `new_split:up`. Valid values are left, right, up, down and auto.
goto_split:
Focus on a split in a given direction. For example `goto_split:up`.
Valid values are left, right, up, down, previous and next.
toggle_split_zoom:
zoom/unzoom the current split.
resize_split:
Resize the current split by moving the split divider in the given
direction. For example `resize_split:left,10`. The valid directions are up, down, left and right.
equalize_splits:
Equalize all splits in the current window
inspector:
Show, hide, or toggle the terminal inspector for the currently focused
terminal.
open_config:
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.
reload_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.
close_surface:
Close the current "surface", whether that is a window, tab, split, etc.
This only closes ONE surface. This will trigger close confirmation as
configured.
close_tab:
Close the current tab, regardless of how many splits there may be.
This will trigger close confirmation as configured.
close_window:
Close the window, regardless of how many tabs or splits there may be.
This will trigger close confirmation as configured.
close_all_windows:
Close all windows. This will trigger close confirmation as configured.
This only works for macOS currently.
toggle_fullscreen:
Toggle fullscreen mode of window.
toggle_window_decorations:
Toggle window decorations on and off. This only works on Linux.
toggle_secure_input:
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.
This applies to the entire application, not just the focused
terminal. You must toggle it off to disable it, or quit Ghostty.
This only works on macOS, since this is a system API on macOS.
toggle_quick_terminal:
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.
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.
To enable the quick terminally globally so that Ghostty doesn't
have to be focused, prefix your keybind with `global`. Example:
\```ini
keybind = global:cmd+grave_accent=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.
See the various configurations for the quick terminal in the
configuration file to customize its behavior.
This currently only works on macOS.
toggle_visibility:
Show/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.
This currently only works on macOS.
quit:
Quit ghostty.
crash:
Crash ghostty in the desired thread for the focused surface.
WARNING: This is a hard crash (panic) and data can be lost.
The purpose of this action is to test crash handling. For some
users, it may be useful to test crash reporting functionality in
order to determine if it all works as expected.
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.
```
</details>
## Testing
- Run `ghostty-dev +list-actions --docs` to verify the new output format
- Check generated _zig-out/share/ghostty/webdata/actions.mdx_ to ensure
all actions are properly documented
Fixes#4522
This is a bit of a hammer-meets-nail solution, but it's a simple
solution to the problem. The reverse mapping is used to find the
binding that an action is bound to, and it's used by apprt's to populate
the accelerator label in the UI.
The problem is that accelerators in GTK are handled early in the event
handling process and its difficult to get that event mapping to a
specific surface. Therefore, the "performable" prefix was not working.
On macOS, this issue didn't exist because there exists an OS mechanism
to install an event handler earlier than the menu system.
This commit changes the reverse mapping to only include bindings that
are not performable. This way, the keybind always reaches the surface
and can be handled by `Surface.keyCallback` which processes
`performable`.
The caveat is that performable bindings will not show up in the UI
for menu items. This is documented in this commit now. They still work,
its just a UI issue.
Two major changes:
1. Hiding uses `NSApp.hide` which hides all windows, preserves tabs, and
yields focus to the next app.
2. Unhiding manually tracks and brings forward only the windows we hid.
Proper focus should be retained.
Fixes#4703
This changes `unbind` so it always removes all keybinds with the given
trigger pattern regardless of if it is translated or physical.
The previous behavior was technically correct, but this implements the pattern
of least surprise. I can't think of a scenario where you really want to
be exact about what key you're unbinding. And if that scenario does
exist, you can always fix it by rebinding after unbind.
In #4388, documentation was added for goto_split but in #3427 this
documentation was made outdated but not updated. This makes the
documentation up to date and brings the ordering in line with new_split
Fixes#4518
If our UTF8 encoding is not recognized, we fall back to the ASCII
mapping of the logical key for the control sequence. This allows
cyrillic control characters to work.
I also verified that non-cyrllic (US) and alternate layouts (Dvorak)
work as expected still.
Fixes#4518
If our UTF8 encoding is not recognized, we fall back to the ASCII
mapping of the logical key for the control sequence. This allows
cyrillic control characters to work.
I also verified that non-cyrllic (US) and alternate layouts (Dvorak)
work as expected still.
Current sort used by `+list-keybinds` doesn't include the value of the
key:
```
ctrl + shift + v paste_from_clipboard
ctrl + shift + a select_all
...
ctrl + shift + q quit
ctrl + shift + n new_window
...
alt + five goto_tab:5
alt + eight goto_tab:8
...
alt + six goto_tab:6
alt + seven goto_tab:7
```
adding the key value improves the sort order
```
ctrl + shift + a select_all
ctrl + shift + c copy_to_clipboard
...
ctrl + shift + n new_window
ctrl + shift + o new_split:right
ctrl + shift + q quit
...
alt + one goto_tab:1
alt + two goto_tab:2
alt + three goto_tab:3
...
alt + eight goto_tab:8
alt + nine last_tab
alt + f4 close_window
closes#4328closes#3970
makes this possible now
```
keybind = performable:ctrl+c=copy_to_clipboard # copy if theres a selection else send sigint
keybind = ctrl+v=paste_from_clipboard
```
Renames the top/bottom directions of `goto_split` to up/down. I have
tested this on linux (nixos) but given that `goto_split` is broken on
linux anyway (#2866) there's not a whole lot to test.
I have no way to build on macOS so I can't verify that I've changed
everything correctly for that.
Closes#3237
The [fixterms](http://www.leonerd.org.uk/hacks/fixterms/) "Really
Special Keypresses" section suggests using CSI 1 ; Ps R for F3, but this
is also a valid cursor position report. The intention was to make
back-compatible changes, so this is fairly considered a specification
bug.
This changes F3 in legacy mode to send CSI 13 ; Ps ~ instead, this is a
variant listed in fixterms, is what kitty protocol uses, and lacks the
problematic overlap with cursor positions.
The KeyEncoder.zig unit test has been changed accordingly, and all tests
pass on my machine.
The [fixterms](http://www.leonerd.org.uk/hacks/fixterms/) "Really
Special Keypresses" section suggests using CSI 1 ; Ps R for F3, but this
is also a valid cursor position report. The intention was to make back-
compatible changes, so this is fairly considered a specification bug.
This changes F3 in legacy mode to send CSI 13 ; Ps ~ instead, this is a
variant listed in fixterms, is what kitty protocol uses, and lacks the
problematic overlap with cursor positions.
The KeyEncoder.zig unit test has been changed accordingly, and all tests
pass on my machine.
The comment in `function_keys.zig` was missing the `>` character for the
sequence. I've confirmed that this was just the comment, Ghostty treats
the original as an SGR sequence, which it is. Conversely, it does treat
`\x1b[>4:2m` as activating modifyOtherKeys.
**Context**
Currently, if there are multiple keybindings with a shared prefix,
they are grouped into a nested series of Binding.Sets.
For example, as reported in #2734, the following bindings:
keybind = ctrl+z>1=goto_tab:1
keybind = ctrl+z>2=goto_tab:2
keybind = ctrl+z>3=goto_tab:3
Result in roughly the following structure (in pseudo-code):
Keybinds{
Trigger("ctrl+z"): Value.leader{
Trigger("1"): Value.leaf{action: "goto_tab:1"},
Trigger("2"): Value.leaf{action: "goto_tab:2"},
Trigger("3"): Value.leaf{action: "goto_tab:3"},
}
}
When this is formatted into a string (and therefore in +list-keybinds),
it is turned into the following as Value.format just concatenates
all the sibling bindings ('1', '2', '3') into consecutive bindings,
and this is then fed into a single configuration entry:
keybind = ctrl+z>1=goto_tab:1>3=goto_tab:3>2=goto_tab:2
**Fix**
To fix this, Value needs to produce a separate configuration entry
for each sibling binding in the Value.leader case.
So we can't produce the entry (formatter.formatEntry) in Keybinds
and need to pass information down the Value tree to the leaf nodes,
each of which will produce a separate entry with that function.
This is accomplished with the help of a new Value.formatEntries method
that recursively builds up the prefix for the keybinding,
finally flushing it to the formatter when it reaches a leaf node.
This is done without extra allocations by using a FixedBufferStream
with the same buffer as before, sharing it between calls to nested
siblings of the same prefix.
**Testing**
Besides the included unit tests, I ran the GLFW-based app
and verified that the resulting binary produced the correct output
with `ghostty +show-config`:
```
❯ .zig-cache//o/02a32e7ba516d2692577a46f1a0df682/ghostty +show-config 2>/dev/null | grep goto_tab
keybind = ctrl+z>1=goto_tab:1
keybind = ctrl+z>3=goto_tab:3
keybind = ctrl+z>2=goto_tab:2
```
**Caveats**
We do not track the order in which the bindings were added
so the order is not retained in the formatConfig output.
Resolves#2734
A common issue for US-centric users of a terminal is that the "option"
key on macOS is not treated as the "alt" key in the terminal.
## Background
macOS does not have an "alt" key, but instead has an "option" key. The "option"
key is used for a variety of purposes, but the troublesome behavior for some
(and expected/desired behavior for others) is that it is used to input special
characters.
For example, on a US standard layout, `option-b` inputs `∫`. This is not
a typically desired character when using a terminal and most users will
instead expect that `option-b` maps to `alt-b` for keybinding purposes
with whatever shell, TUI, editor, etc. they're using.
On non-US layouts, the "option" key is a critical modifier key for
inputting certain characters in the same way "shift" is a critical
modifier key for inputting certain characters on US layouts.
We previously tried to change the default for `macos-option-as-alt`
to `left` (so that the left option key behaves as alt) because I had the
wrong assumption that international users always used the right option
key with terminals or were used to this. But very quickly beta users
with different layouts (such as German, I believe) noted that this is
not the case and broke their idiomatic input behavior. This behavior was
therefore reverted.
## Solution
This confusing behavior happened frequently enough that I decided to
implement the more complex behavior in this commit. The new behavior is
that when a US layout is active, `macos-option-as-alt` defaults to true
if it is unset. When a non-US layout is active, `macos-option-as-alt`
defaults to false if it is unset. This happens live as users change
their keyboard layout.
**An important goal of Ghostty is to have zero-config defaults** that
satisfy the majority of users. Fiddling with configurations is -- for
most -- an annoying task and software that works well enough out of the
box is delightful. Based on surveying beta users, I believe this commit
will result in less configuration for the majority of users.
## Other Terminals
This behavior is unique amongst terminals as far as I know.
Terminal.app, Kitty, iTerm2, Alacritty (I stopped checking there) all
default to the default macOS behavior (option is option and special
characters are inputted).
All of the aforementioned terminals have a setting to change this
behavior, identical to Ghostty (or, Ghostty identical to them perhaps
since they all predate Ghostty).
I couldn't find any history where users requested the behavior of
defaulting this to something else for US based keyboards. That's
interesting since this has come up so frequently during the Ghostty
beta!
**Context**
Currently, if there are multiple keybindings with a shared prefix,
they are grouped into a nested series of Binding.Sets.
For example, as reported in #2734, the following bindings:
keybind = ctrl+z>1=goto_tab:1
keybind = ctrl+z>2=goto_tab:2
keybind = ctrl+z>3=goto_tab:3
Result in roughly the following structure (in pseudo-code):
Keybinds{
Trigger("ctrl+z"): Value.leader{
Trigger("1"): Value.leaf{action: "goto_tab:1"}),
Trigger("2"): Value.leaf{action: "goto_tab:2"}),
Trigger("3"): Value.leaf{action: "goto_tab:3"}),
}
}
When this is formatted into a string (and therefore in +list-keybinds),
it is turned into the following as Value.format just concatenates
all the sibling bindings ('1', '2', '3') into consecutive bindings,
and this is then fed into a single configuration entry:
keybind = ctrl+z>1=goto_tab:1>3=goto_tab:3>2=goto_tab:2
**Fix**
To fix this, Value needs to produce a separate configuration entry
for each sibling binding in the Value.leader case.
So we can't produce the entry (formatter.formatEntry) in Keybinds
and need to pass information down the Value tree to the leaf nodes,
each of which will produce a separate entry with that function.
This is accomplished with the help of a new Value.formatEntries method
that recursively builds up the prefix for the keybinding,
finally flushing it to the formatter when it reaches a leaf node.
This is done without extra allocations by using a FixedBufferStream
with the same buffer as before, sharing it between calls to nested
siblings of the same prefix.
**Caveats**
We do not track the order in which the bindings were added
so the order is not retained in the formatConfig output.
Resolves#2734
