zsh: document unsupported system-level ZDOTDIR

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.
This commit is contained in:
Jon Parise
2025-12-14 19:21:45 -05:00
parent 1d7fe9e70d
commit b0c053cfb7

View File

@@ -78,10 +78,16 @@ on the Fish startup process, see the
### Zsh
For `zsh`, Ghostty sets `ZDOTDIR` so that it loads our configuration
from the `zsh` directory. The existing `ZDOTDIR` is retained so that
after loading the Ghostty shell integration the normal Zsh loading
sequence occurs.
Automatic [Zsh](https://www.zsh.org/) integration works by temporarily setting
`ZDOTDIR` to our `zsh` directory. An existing `ZDOTDIR` environment variable
value will be retained and restored after our shell integration scripts are
run.
However, if `ZDOTDIR` is set in a system-wide file like `/etc/zshenv`, it will
override Ghostty's `ZDOTDIR` value, preventing the shell integration from being
loaded. In this case, the shell integration needs to be loaded manually.
To load the Zsh shell integration manually:
```zsh
if [[ -n $GHOSTTY_RESOURCES_DIR ]]; then