26.11 User Configuration Functions

The zsh/newuser module comes with a function to aid in configuring shell options for new users. If the module is installed, this function can also be run by hand. It is available even if the module’s default behaviour, namely running the function for a new user logging in without startup files, is inhibited.

zsh-newuser-install [ -f ]

The function presents the user with various options for customizing their initialization scripts. Currently only ~/.zshrc is handled. $ZDOTDIR/.zshrc is used instead if the parameter ZDOTDIR is set; this provides a way for the user to configure a file without altering an existing .zshrc.

By default the function exits immediately if it finds any of the files .zshenv, .zprofile, .zshrc, or .zlogin in the appropriate directory. The option -f is required in order to force the function to continue. Note this may happen even if .zshrc itself does not exist.

As currently configured, the function will exit immediately if the user has root privileges; this behaviour cannot be overridden.

Once activated, the function’s behaviour is supposed to be self-explanatory. Menus are present allowing the user to alter the value of options and parameters. Suggestions for improvements are always welcome.

When the script exits, the user is given the opportunity to save the new file or not; changes are not irreversible until this point. However, the script is careful to restrict changes to the file only to a group marked by the lines ‘# Lines configured by zsh-newuser-install’ and ‘# End of lines configured by zsh-newuser-install’. In addition, the old version of .zshrc is saved to a file with the suffix .zni appended.

If the function edits an existing .zshrc, it is up to the user to ensure that the changes made will take effect. For example, if control usually returns early from the existing .zshrc the lines will not be executed; or a later initialization file may override options or parameters, and so on. The function itself does not attempt to detect any such conflicts.