From b0c053cfb7a69e81da2f0eb9e411db31bd11c1b0 Mon Sep 17 00:00:00 2001 From: Jon Parise Date: Sun, 14 Dec 2025 19:21:45 -0500 Subject: [PATCH] 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. --- src/shell-integration/README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/shell-integration/README.md b/src/shell-integration/README.md index 3f8543c68..9c422ef26 100644 --- a/src/shell-integration/README.md +++ b/src/shell-integration/README.md @@ -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