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.
pull/9911/head
Jon Parise 2025-12-14 19:21:45 -05:00
parent 1d7fe9e70d
commit b0c053cfb7
1 changed files with 10 additions and 4 deletions

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