@@ -15,6 +15,24 @@ let
1515 (filterAttrs (k: v: v != null) cfg.shellAliases)
1616 );
1717
18+ zshStartupNotes = ''
19+ # Note that generated /etc/zprofile and /etc/zshrc files do a lot of
20+ # non-standard setup to make zsh usable with no configuration by default.
21+ #
22+ # Which means that unless you explicitly meticulously override everything
23+ # generated, interactions between your ~/.zshrc and these files are likely
24+ # to be rather surprising.
25+ #
26+ # Note however, that you can disable loading of the generated /etc/zprofile
27+ # and /etc/zshrc (you can't disable loading of /etc/zshenv, but it is
28+ # designed to not set anything surprising) by setting `no_global_rcs` option
29+ # in ~/.zshenv:
30+ #
31+ # echo setopt no_global_rcs >> ~/.zshenv
32+ #
33+ # See "STARTUP/SHUTDOWN FILES" section of zsh(1) for more info.
34+ '';
35+
1836in
1937
2038{
@@ -69,6 +87,10 @@ in
6987
7088 promptInit = mkOption {
7189 default = ''
90+ # Note that to manually override this in ~/.zshrc you should run `prompt off`
91+ # before setting your PS1 and etc. Otherwise this will likely to interact with
92+ # your ~/.zshrc configuration in unexpected ways as the default prompt sets
93+ # a lot of different prompt variables.
7294 autoload -U promptinit && promptinit && prompt walters && setopt prompt_sp
7395 '';
7496 description = ''
@@ -100,7 +122,8 @@ in
100122 ];
101123 example = [ "EXTENDED_HISTORY" "RM_STAR_WAIT" ];
102124 description = ''
103− Configure zsh options.
125+ Configure zsh options. See
126+ <citerefentry><refentrytitle>zshoptions</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
104127 '';
105128 };
106129
@@ -149,11 +172,12 @@ in
149172
150173 HELPDIR="${pkgs.zsh}/share/zsh/$ZSH_VERSION/help"
151174
152− # Tell zsh how to find installed completions
175+ # Tell zsh how to find installed completions.
153176 for p in ''${(z)NIX_PROFILES}; do
154177 fpath+=($p/share/zsh/site-functions $p/share/zsh/$ZSH_VERSION/functions $p/share/zsh/vendor-completions)
155178 done
156179
180+ # Setup custom shell init stuff.
157181 ${cfge.shellInit}
158182
159183 ${cfg.shellInit}
@@ -168,11 +192,14 @@ in
168192 ''
169193 # /etc/zprofile: DO NOT EDIT -- this file has been generated automatically.
170194 # This file is read for login shells.
195+ #
196+ ${zshStartupNotes}
171197
172198 # Only execute this file once per shell.
173199 if [ -n "$__ETC_ZPROFILE_SOURCED" ]; then return; fi
174200 __ETC_ZPROFILE_SOURCED=1
175201
202+ # Setup custom login shell init stuff.
176203 ${cfge.loginShellInit}
177204
178205 ${cfg.loginShellInit}
@@ -187,31 +214,44 @@ in
187214 ''
188215 # /etc/zshrc: DO NOT EDIT -- this file has been generated automatically.
189216 # This file is read for interactive shells.
217+ #
218+ ${zshStartupNotes}
190219
191220 # Only execute this file once per shell.
192221 if [ -n "$__ETC_ZSHRC_SOURCED" -o -n "$NOSYSZSHRC" ]; then return; fi
193222 __ETC_ZSHRC_SOURCED=1
194223
195− . /etc/zinputrc
224+ ${optionalString (cfg.setOptions != []) ''
225+ # Set zsh options.
226+ setopt ${concatStringsSep " " cfg.setOptions}
227+ ''}
196228
197− # Don't export these, otherwise other shells (bash) will try to use same histfile
229+ # Setup command line history.
230+ # Don't export these, otherwise other shells (bash) will try to use same HISTFILE.
198231 SAVEHIST=${toString cfg.histSize}
199232 HISTSIZE=${toString cfg.histSize}
200233 HISTFILE=${cfg.histFile}
201234
202− ${optionalString cfg.enableGlobalCompInit "autoload -U compinit && compinit"}
235+ # Configure sane keyboard defaults.
236+ . /etc/zinputrc
203237
238+ ${optionalString cfg.enableGlobalCompInit ''
239+ # Enable autocompletion.
240+ autoload -U compinit && compinit
241+ ''}
242+
243+ # Setup custom interactive shell init stuff.
204244 ${cfge.interactiveShellInit}
205245
206246 ${cfg.interactiveShellInit}
207247
208− ${optionalString (cfg.setOptions != []) "setopt ${concatStringsSep " " cfg.setOptions}"}
209−
248+ # Setup aliases.
210249 ${zshAliases}
211250
251+ # Setup prompt.
212252 ${cfg.promptInit}
213253
214− # Need to disable features to support TRAMP
254+ # Disable some features to support TRAMP.
215255 if [ "$TERM" = dumb ]; then
216256 unsetopt zle prompt_cr prompt_subst
217257 unfunction precmd preexec