Applied-Software/ghostty
5
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2025-07-16 08:46:08 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: expand SSH integration configuration documentation

Browse Source 
Add detailed explanations of shell function behavior, TERM compatibility
trade-offs, environment variable propagation, and authentication
requirements per maintainer feedback.
This commit is contained in:
Jason Rayne
2025-06-16 16:19:14 -07:00
parent 4206ab1210
commit 8fafd5ace1
1 changed files with 22 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
src/config/Config.zig
View File

@ -1975,18 +1975,32 @@ keybind: Keybinds = .{},
/// Example: `cursor`, `no-cursor`, `sudo`, `no-sudo`, `title`, `no-title`
@"shell-integration-features": ShellIntegrationFeatures = .{},
/// SSH integration levels for shell integration.
/// Controls how much SSH integration is performed when connecting to remote hosts.
/// SSH integration configuration for shell integration.
///
/// When enabled (any value other than `off`), Ghostty replaces the `ssh` command
/// with a shell function to provide enhanced terminal compatibility and feature
/// propagation when connecting to remote hosts. Users can verify this by running
/// `type ssh` which will show "ssh is a shell function" instead of the binary path.
///
/// Allowable values are:
///
/// * `off` - No SSH integration, use standard ssh command
/// * `off` - No SSH integration, use standard ssh binary
///
/// * `term-only` - Only fix TERM compatibility (xterm-ghostty -> xterm-256color)
/// * `term-only` - Automatically converts TERM from `xterm-ghostty` to `xterm-256color`
/// when connecting to remote hosts. This prevents "unknown terminal type" errors
/// on systems that lack Ghostty's terminfo entry, but sacrifices Ghostty-specific
/// terminal features like enhanced cursor reporting and shell integration markers.
/// See: https://ghostty.org/docs/help/terminfo
///
/// * `basic` - TERM fix + environment variable propagation
/// * `basic` - TERM compatibility fix plus environment variable propagation.
/// Forwards `GHOSTTY_SHELL_FEATURES` to enable shell integration features on
/// remote systems that have Ghostty installed and configured.
///
/// * `full` - All features: TERM fix + env vars + terminfo installation
/// * `full` - All basic features plus automatic terminfo installation. Attempts
/// to install Ghostty's terminfo entry on the remote host using `infocmp` and `tic`,
/// then connects with full `xterm-ghostty` support. Requires two SSH authentications
/// (one for installation, one for the session) but enables complete Ghostty
/// terminal functionality on the remote system.
///
/// The default value is `off`.
@"ssh-integration": SSHIntegration = .off,
@ -6114,20 +6128,7 @@ pub const ShellIntegrationFeatures = packed struct {
title: bool = true,
};
/// SSH integration levels for shell integration.
/// Controls how much SSH integration is performed when connecting to remote hosts.
///
/// Allowable values are:
///
/// * `off` - No SSH integration, use standard ssh command
///
/// * `term-only` - Only fix TERM compatibility (xterm-ghostty -> xterm-256color)
///
/// * `basic` - TERM fix + environment variable propagation
///
/// * `full` - All features: TERM fix + env vars + terminfo installation + shell integration injection
///
/// The default value is `off`.
/// See ssh-integration
pub const SSHIntegration = enum {
off,
@"term-only",
@ -7678,3 +7679,4 @@ test "theme specifying light/dark sets theme usage in conditional state" {
try testing.expect(cfg._conditional_set.contains(.theme));
}
}