Merge pull request #67376 from oxij/nixos/zsh-doc

nixos: zsh: add more helpful documentation into generated files

Changed files
+53 -13
nixos
modules
programs
zsh
+53 -13
nixos/modules/programs/zsh/zsh.nix
···
(filterAttrs (k: v: v != null) cfg.shellAliases)
);
+
zshStartupNotes = ''
+
# Note that generated /etc/zprofile and /etc/zshrc files do a lot of
+
# non-standard setup to make zsh usable with no configuration by default.
+
#
+
# Which means that unless you explicitly meticulously override everything
+
# generated, interactions between your ~/.zshrc and these files are likely
+
# to be rather surprising.
+
#
+
# Note however, that you can disable loading of the generated /etc/zprofile
+
# and /etc/zshrc (you can't disable loading of /etc/zshenv, but it is
+
# designed to not set anything surprising) by setting `no_global_rcs` option
+
# in ~/.zshenv:
+
#
+
# echo setopt no_global_rcs >> ~/.zshenv
+
#
+
# See "STARTUP/SHUTDOWN FILES" section of zsh(1) for more info.
+
'';
+
in
{
···
promptInit = mkOption {
default = ''
+
# Note that to manually override this in ~/.zshrc you should run `prompt off`
+
# before setting your PS1 and etc. Otherwise this will likely to interact with
+
# your ~/.zshrc configuration in unexpected ways as the default prompt sets
+
# a lot of different prompt variables.
autoload -U promptinit && promptinit && prompt walters && setopt prompt_sp
'';
description = ''
···
];
example = [ "EXTENDED_HISTORY" "RM_STAR_WAIT" ];
description = ''
-
Configure zsh options.
+
Configure zsh options. See
+
<citerefentry><refentrytitle>zshoptions</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
'';
};
···
. ${config.system.build.setEnvironment}
fi
+
HELPDIR="${pkgs.zsh}/share/zsh/$ZSH_VERSION/help"
+
+
# Tell zsh how to find installed completions.
+
for p in ''${(z)NIX_PROFILES}; do
+
fpath+=($p/share/zsh/site-functions $p/share/zsh/$ZSH_VERSION/functions $p/share/zsh/vendor-completions)
+
done
+
+
# Setup custom shell init stuff.
${cfge.shellInit}
${cfg.shellInit}
···
''
# /etc/zprofile: DO NOT EDIT -- this file has been generated automatically.
# This file is read for login shells.
+
#
+
${zshStartupNotes}
# Only execute this file once per shell.
if [ -n "$__ETC_ZPROFILE_SOURCED" ]; then return; fi
__ETC_ZPROFILE_SOURCED=1
+
# Setup custom login shell init stuff.
${cfge.loginShellInit}
${cfg.loginShellInit}
···
''
# /etc/zshrc: DO NOT EDIT -- this file has been generated automatically.
# This file is read for interactive shells.
+
#
+
${zshStartupNotes}
# Only execute this file once per shell.
if [ -n "$__ETC_ZSHRC_SOURCED" -o -n "$NOSYSZSHRC" ]; then return; fi
__ETC_ZSHRC_SOURCED=1
-
. /etc/zinputrc
+
${optionalString (cfg.setOptions != []) ''
+
# Set zsh options.
+
setopt ${concatStringsSep " " cfg.setOptions}
+
''}
-
# Don't export these, otherwise other shells (bash) will try to use same histfile
+
# Setup command line history.
+
# Don't export these, otherwise other shells (bash) will try to use same HISTFILE.
SAVEHIST=${toString cfg.histSize}
HISTSIZE=${toString cfg.histSize}
HISTFILE=${cfg.histFile}
-
HELPDIR="${pkgs.zsh}/share/zsh/$ZSH_VERSION/help"
+
# Configure sane keyboard defaults.
+
. /etc/zinputrc
-
# Tell zsh how to find installed completions
-
for p in ''${(z)NIX_PROFILES}; do
-
fpath+=($p/share/zsh/site-functions $p/share/zsh/$ZSH_VERSION/functions $p/share/zsh/vendor-completions)
-
done
-
-
${optionalString cfg.enableGlobalCompInit "autoload -U compinit && compinit"}
+
${optionalString cfg.enableGlobalCompInit ''
+
# Enable autocompletion.
+
autoload -U compinit && compinit
+
''}
+
# Setup custom interactive shell init stuff.
${cfge.interactiveShellInit}
${cfg.interactiveShellInit}
-
${optionalString (cfg.setOptions != []) "setopt ${concatStringsSep " " cfg.setOptions}"}
-
+
# Setup aliases.
${zshAliases}
+
# Setup prompt.
${cfg.promptInit}
-
# Need to disable features to support TRAMP
+
# Disable some features to support TRAMP.
if [ "$TERM" = dumb ]; then
unsetopt zle prompt_cr prompt_subst
unset RPS1 RPROMPT