PROMPT_COMMAND array support for introduced in bash 5.1, and it's the
preferred format moving forward. Using the string form is also fine, but
it's easy to be a modern bash citizen here, so let's do so.
bash-preexec implements support for its "precmd" and "preexec" hooks
using a combination of PROMPT_COMMAND and a DEBUG trap. The latter is
unfortunately quick slow (in a relative sense), and the overall system
is a bit more generalized than what we need for our shell integration
(e.g. supporting multiple function hooks, subshells, etc.).
Bash 4.4 introduced the PS0 variable, which is expanded and displayed by
interactive shells after reading a complete command but before executing
it. This is all we need to implement our own shell integration hooks.
In Bash 5.1, PROMPT_COMMAND can be an array variable, each element of
which can contain a command to be executed like a string PROMPT_COMMAND
variable. When adding our hook to PROMPT_COMMAND, we preserve its type
(string or array) to be minimally intrusive. This also matches direnv's
approach.
Bash 5.3 introduced support for function substitution, which is an even
more efficient way to run code from PS0, so we use that when available.
Otherwise, we use the more traditional command substitution approach.
Earlier versions of bash (such as 3.2, which still ships with macOS)
continue to use the bash-preexec path. This gives us two code paths to
maintain, but I think that's preferable to fully maintaining our own
DEBUG trap-based system for older bash versions given that bash-preexec
has proven to work reliably in those environments. We also wouldn't
unlock any other user benefits aside from removing the bash-preexec
script dependency.
See: #3724, #7734
We always add GHOSTTY_SHELL_INTEGRATION_XDG_DIR to XDG_DATA_DIRS with a
tailing colon (via our prependEnv routine), so we can greatly simplify
this cleanup code with a single str:replace call.
We always add GHOSTTY_SHELL_INTEGRATION_XDG_DIR to XDG_DATA_DIRS with a
tailing colon (via our prependEnv routine), so we can greatly simplify
this cleanup code with a single str:replace call.
This adds support for the `OSC 133 A click_events=1` extension
introduced by Kitty and supported by Fish.[^1]
**What this means:** If the shell advertises `click_events=1` support,
Ghostty will _unconditionally_ (no modifier required) send mouse events
to the shell for clicks on a prompt line, delegating to the supporting
shell to move the cursor as needed. For Fish 4.1+ this means that
clicking on the prompt line moves the cursor (see demo video below).
This PR also contains:
* A minor fix in `cl` parsing but we don't yet implement the logic there
* Updated inspector to show the semantic prompt click mode
## Demo
https://github.com/user-attachments/assets/03ef8975-7ad9-441f-aaa2-9d0eb5c5e36d
## Implementation Details
`click_events` is wildly underspecified, so here are the details the
best I understand them. This itself is not a specification (I omit
details) but adds some more context to it.
The `click_events=1` option can be specified with `OSC 133 A` (Ghostty
also allows it on OSC 133 N). When that is specified, it flags for all
future prompts that the screen supports click events for semantic
prompts. If both `click_events` and `cl` are specified, `click_events`
takes priority if true. If `click_events=0` (disable), then any set `cl`
will take priority.
When a mouse click comes in, we check for the following conditions:
1. The screen supports click events
2. The screen cursor is currently at a prompt
3. The mouse click was at or below the starting prompt line of the
current prompt
If those are met, we encode an SGR mouse event with: left button, press,
coordinates of click. It is up to the shell after that to handle it. Out
of prompt bounds SGR events are possible (specifically below). The shell
should robustly handle this.
[^1]: I don't know any other terminal or shell that supports it at the
moment.
Wrapping `use ghostty-integration` in a `try .. catch` here makes this
suggestion more resilient to environments where we didn't inject our
resource directory into XDG_DATA_DIRS (but are still running Ghostty).
The ssh wrapper previously used a separate set_ssh_terminfo function
that returned a record to be merged, which result in some redundant
control flow and TERM assignments.
This inlines the terminfo logic and builds env/opts incrementally based
on feature flags. TERM is set to a fallback early and only overridden on
success, which simplifies our error handling and avoids mutable variable
capture issues in closures.
Lastly, warnings are now consistently written to stderr, and I made
various other control flow and syntax improvements.
Wrapping `use ghostty-integration` in a `try .. catch` here makes this
suggestion more resilient to environments where we didn't inject our
resource directory into XDG_DATA_DIRS (but are still running Ghostty).
This reporting shouldn't have been tied to the 'title' shell features.
That's a different feature where we change the window title (icon) to
reflect the current command using OSC 2.
Insert OSC 133 A k=s marks after each newline in PS1, so that all lines
following the first are marked as secondary prompts. This prevents ghostty
from erasing leading lines during terminal resize.
The ssh wrapper previously used a separate set_ssh_terminfo function
that returned a record to be merged, which result in some redundant
control flow and TERM assignments.
This inlines the terminfo logic and builds env/opts incrementally based
on feature flags. TERM is set to a fallback early and only overridden on
success, which simplifies our error handling and avoids mutable variable
capture issues in closures.
Lastly, warnings are now consistently written to stderr, and I made
various other control flow and syntax improvements.
Nushell <https://www.nushell.sh/> is a modern interactive shell that
provides many shell features out-of-the-box, like `title` support. Our
shell integration therefore focuses on Ghostty-specific features like
`sudo`.
We use Nushell's module system to provide a `ghostty` module containing
our shell integration features. This module is automatically loaded from
$XDG_DATA_DIRS/nushell/vendor/autoload/ when `nushell` shell integration
is enabled.
Exported module functions need to be explicitly "used" before they're
available to the interactive shell environment. We do that automatically
by adding `--execute "use ghostty *"` to the `nu` command line.
This imports all available functions, and individual shell features are
runtime-guarded by the script code (using $GHOSTTY_SHELL_FEATURES). We
can consider further refining this later.
When automatic shell integration is disabled, users can still manually
source and enable the shell integration module:
source
$GHOSTTY_RESOURCES_DIR/shell-integration/nushell/vendor/autoload/ghostty.nu
use ghostty *
This initial work implements our TERMINFO-aware `sudo` wrapper (via the
`sudo` shell feature). Support for additional features, like `ssh-env`
and `ssh-terminfo`, will follow (#9604).
The zsh shell integration was using `${(V)1}` parameter expansion to set
the window title, which converts control characters to their visible
escape sequence representations. This caused commands ending with a
newline to display as `command\n` in the title bar.
Changed to use `${1//[[:cntrl:]]}` which strips control characters
entirely, matching the behavior of the bash integration.
Nushell <https://www.nushell.sh/> is a modern interactive shell that
provides many shell features out-of-the-box, like `title` support. Our
shell integration therefore focuses on Ghostty-specific features like
`sudo`.
We use Nushell's module system to provide a `ghostty` module containing
our shell integration features. This module is automatically loaded from
$XDG_DATA_DIRS/nushell/vendor/autoload/ when `nushell` shell integration
is enabled.
Exported module functions need to be explicitly "used" before they're
available to the interactive shell environment. We do that automatically
by adding `--execute "use ghostty *"` to the `nu` command line.
This imports all available functions, and individual shell features are
runtime-guarded by the script code (using $GHOSTTY_SHELL_FEATURES). We
can consider further refining this later.
When automatic shell integration is disabled, users can still manually
source and enable the shell integration module:
source $GHOSTTY_RESOURCES_DIR/shell-integration/nushell/vendor/autoload/ghostty.nu
use ghostty *
This initial work implements our TERMINFO-aware `sudo` wrapper (via the
`sudo` shell feature). Support for additional features, like `ssh-env`
and `ssh-terminfo`, will follow.
We rely on temporarily setting ZDOTDIR to our `zsh` resource directory
to implement automatic shell integration. Setting ZDOTDIR in a system
file like /etc/zshenv overrides our ZDOTDIR value, preventing our shell
integration from being loaded.
The only way to prevent /etc/zshenv from being run is via the --no-rcs
flag. (The --no-globalrcs only applies to system-level files _after_
/etc/zshenv is loaded.) Unfortunately, there doesn't appear to be a way
to run a "bootstrap" script (to reimplement the Zsh startup sequence
manually, similar to how our bash integration works) and then enter an
interactive shell session.
https://zsh.sourceforge.io/Doc/Release/Files.html
Given all of the above, document this as an unsupported configuration
for automatic shell integration and point affected users at our manual
shell integration option.
Due to security issues, `sudo` implementations may not preserve
environment variables unless appended with `--preserve-env=list`.
Signed-off-by: definfo <hjsdbb1@gmail.com>
The main thing to emphasize is that end users should never source
.zshenv directly; it's only meant to be used as part of our shell
injection environment.
At the moment, there's no way to guard against accidentally use, but we
can consider making e.g. GHOSTTY_SHELL_FEATURES always defined in this
environment to that it can be used to differentiate the cases.
In practice, it's unlikely that people actually source this .zshenv
script directly, so hopefully this additional documentation clarifies
things well enough.
The ghostty-integration script can be manually sourced, and it uses the
Zsh 5.1+ features, so that's a better place to guard against older Zsh
versions.
This also keeps the .zshenv script focused on just bootstrapping our
automatic shell integration.
I also changed the version check to a slightly more idiomatic pattern.
The main thing to emphasize is that end users should never source
.zshenv directly; it's only meant to be used as part of our shell
injection environment.
At the moment, there's no way to guard against accidentally use, but we
can consider making e.g. GHOSTTY_SHELL_FEATURES always defined in this
environment to that it can be used to differentiate the cases.
In practice, it's unlikely that people actually source this .zshenv
script directly, so hopefully this additional documentation clarifies
things well enough.
`fish_add_path` by default updates the `fish_user_paths` universal
variable which makes the modification persist across shell sessions.
The integration also tries to update the `fish_user_paths` when the
desired path already appears in the `PATH` environment variable but
not in `fish_user_paths`. Because `fish_user_paths` will always be
inserted before the inherited `PATH` env. This makes the added path
unintentionally has a higher priority.
This patch makes the above issues by adding `--global` and `--path`
options to `fish_user_paths` which limits the modification scope and
ensures that the path won't be added if it already exists in `PATH`.
Previously, the fish shell integration interfered with fish's builtin vi
mode cursor switching configurations such as `$fish_cursor_default` and
`$fish_cursor_insert`.
```console
$ ghostty --config-default-files=false -e fish --no-config --init-command 'source "$GHOSTTY_RESOURCES_DIR"/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish; fish_vi_key_bindings'
```
The above command starts fish in vi mode with Ghostty shell
integrations. Manually loading the integration is necessary due to
`--no-config` blocking auto injection.
1. At the prompt, fish is in insert mode, and the cursor is a blinking
beam. However, press escape and then "i" to exit then re-enter insert
mode, and the cursor will be a solid beam due to the
`$fish_cursor_unknown` setting. Without the shell integration, insert
mode always uses a solid beam cursor.
2. A similar problem shows if we start fish with `fish_vi_key_bindings
default`. The cursor ends up as a blinking beam in normal mode only due
to the shell integration interfering. This glitch can also be reset away
by entering then exiting insert mode.
3. Also, `$fish_cursor_external` has no effect when used with shell
integration. After `fish_vi_key_bindings`, set it to `line`, run cat(1),
and shell integration will give you a blinking block, not the asked for
line/beam.
I verified that this patch makes the shell integration stop interfering
in three scenarios above, and it still changes the cursor when not using
fish's vi mode.
Note that `$fish_cursor_*` variables can be set when fish isn't in vi
mode, so they're not great signals for the shell integration hooks.
This fixes the incorrect comment and uses $HOME (rather than ~) to be a
little bit more explicit.
Also, our script is named ghostty-integration, not ghostty.zsh, so
update that part of the comment, too.
As discussed here https://github.com/ghostty-org/ghostty/discussions/8021
This fixes invalid fish shell syntax.
As an example, run ghostty like so: `XDG_CONFIG_HOME=/tmp ghostty --shell-integration-features=ssh-env --command="/usr/bin/env fish"`. Setting XDG_CONFIG_HOME to /tmp is just to start from the default config.
Before:
```
Welcome to fish, the friendly interactive shell
Type help for instructions on how to use fish
robbiev@neo ~/s/ghostty (fish-shell-ssh)> ssh git@github.com
env: ‘command’: No such file or directory
robbiev@neo ~/s/ghostty (fish-shell-ssh) [127]>
```
After:
```
Welcome to fish, the friendly interactive shell
Type help for instructions on how to use fish
robbiev@neo ~/s/ghostty (fish-shell-ssh)> ssh git@github.com
PTY allocation request failed on channel 0
Hi robbiev! You've successfully authenticated, but GitHub does not provide shell access.
Connection to github.com closed.
robbiev@neo ~/s/ghostty (fish-shell-ssh) [1]>
```
My understanding of the fix follows.
The script is using `command` to make sure it calls the actual ssh binary and not some intermediate shell function with the same name (`man command` explains).
`env` can be useful for fish compat < 3.1, where [the KEY=value syntax was introduced](https://fishshell.com/docs/current/faq.html#how-do-i-set-or-clear-an-environment-variable). However because `command` is a builtin it doesn't work in this case.
So a simple solution is this, requiring fish >= 3.1
```
TERM="$ssh_term" command ssh $ssh_opts $argv
```
An [alternative](https://serverfault.com/questions/164305/how-can-i-set-environment-variable-for-just-one-command-in-fish-shell) for maximum fish compat could be the following:
```
begin
set -lx TERM "$ssh_term"
command ssh $ssh_opts $argv
end
```
According to `man set`, `-l` means local to the block and `-x` means export.
I'm in favour of keeping `command` as it makes the integration more predicable.
The reason I went with the current fix:
- It's easier to understand without knowing fish shell.
- [kat found that fish 3.1 should be widely available](https://github.com/ghostty-org/ghostty/discussions/8021#discussioncomment-13877129).
