From fdc21e6656d3a20f46a4c80991752f23cc29ede6 Mon Sep 17 00:00:00 2001 From: Jon Parise Date: Mon, 13 Apr 2026 10:01:11 -0400 Subject: [PATCH] shell-integration: clarify ssh config workaround scope Move the ~/.ssh/config workaround into its own subsection so it reads as an alternative rather than a universal recommendation, and add a note warning that `SetEnv TERM=xterm-256color` will downgrade TERM on hosts that already have the xterm-ghostty terminfo entry installed. --- docs/features/shell-integration.mdx | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/features/shell-integration.mdx b/docs/features/shell-integration.mdx index 7fd1a415..81ab5705 100644 --- a/docs/features/shell-integration.mdx +++ b/docs/features/shell-integration.mdx @@ -214,9 +214,12 @@ The `ssh` shell function will _not_ be used in the following cases: `Makefile` recipes, `cron` jobs, and command substitutions in other programs. -For any of these cases, the most robust workaround is to configure -`SetEnv` and `SendEnv` directly in `~/.ssh/config`, which applies to -every `ssh` invocation regardless of how it was launched: +### Manual `~/.ssh/config` Configuration + +If you need `TERM` and environment forwarding for cases the shell wrapper +can't cover (see above), you can configure `SetEnv` and `SendEnv` +directly in `~/.ssh/config`, which applies to every `ssh` invocation +regardless of how it was launched: ```ssh-config # ~/.ssh/config @@ -232,6 +235,12 @@ Host example.com manually. + + If the remote host already has the `xterm-ghostty` terminfo entry + installed, a `SetEnv TERM=xterm-256color` stanza will unnecessarily + downgrade `TERM`. Only use this for hosts that lack the terminfo entry. + + ### Remote `sshd` Configuration The `ssh-env` feature uses `SendEnv` to forward `COLORTERM`,