SixArm.com → Z shell → zsh configuration
We use Z shell extensively, on many kinds of systems. We use Z shell configurations and conventions that can help us with compatibility, flexibility, and portability. This repo describes our configurations and conventions. This repo has our typical starter setup for Z shell aliases, functions, settings, etc. In practice this works well with other Z shell tools, such as oh-my-zsh.
There are five startup files that zsh will read commands from in order:
zshenv
zprofile
zshrc
zlogin
zlogout
zshenv
is sourced on all invocations of the shell, unless the -f option is set.
What goes in it:
Set up the command search path
Other important environment variables
Commands to set up aliases and functions that are needed for other scripts
What does NOT go in it:
Commands that produce output
Anything that assumes the shell is attached to a tty
zprofile
is sourced in login shells. It is meant as an alternative to zlogin
for ksh
fans; the two are not intended to be used together, although this could certainly be done if desired.
What goes in it:
Commands that should be executed only in login shells.
As a general rule, it should not change the shell environment at all.
As a general rule, set the terminal type then run a series of external commands e.g. fortune, msgs, etc.
What does NOT go in it:
Alias definitions
Function definitions
Options
Environment variable settings
zshrc
is sourced in interactive shells.
What goes in it:
zlogin
is like zprofile
, except sourced after zshrc.
zlogout
is sourced when login shells exit.
Some zsh setups provide more files that are not read by zsh:
.zsh-update
: contains a timestamp of the most recent update
.zshrc-e
: an example file; the Z shell convention is example files end in -e
.
The default location for zsh system files:
/etc/zshenv
/etc/zprofile
/etc/zshrc
/etc/zlogin
/etc/zlogout
The default location for zsh user files:
$HOME/.zshenv
$HOME/.zprofile
$HOME/.zshrc
$HOME/.zlogin
$HOME/.zlogout
The custom location for zsh user files uses the environment variable ZDOTDIR
:
${ZDOTDIR:-$HOME}/.zshenv
${ZDOTDIR:-$HOME}/.zprofile
${ZDOTDIR:-$HOME}/.zshrc
${ZDOTDIR:-$HOME}/.zlogin
${ZDOTDIR:-$HOME}/.zlogout
Our location for zsh system directories:
/etc/zshenv.d
/etc/zprofile.d
/etc/zshrc.d
/etc/zlogin.d
/etc/zlogout.d
Our default location for zsh user directories:
$HOME/.config/zshenv.d
$HOME/.config/zprofile.d
$HOME/.config/zshrc.d
$HOME/.config/zlogin.d
$HOME/.config/zlogout.d
Our custom location for zsh user directories uses the environment variable XDG_CONFIG_HOME
:
${XDG_CONFIG_HOME:-$HOME/.config}/zshenv.d
${XDG_CONFIG_HOME:-$HOME/.config}/zprofile.d
${XDG_CONFIG_HOME:-$HOME/.config}/zshrc.d
${XDG_CONFIG_HOME:-$HOME/.config}/zlogin.d
${XDG_CONFIG_HOME:-$HOME/.config}/zlogout.d
This repo contains our Z shell conventions for subdirectories and also our files that we like to use with multiple teams.
Notable subdirectories:
zshenv.d/functions
is for functions.
zshenv.d/programs
is for configuring environment programs via environment variables, such as $EDITOR
, $PAGER
, etc.
zshenv.d/settings
is for Z shell settings, such as for completion, history, etc.
zshrc.d/aliases
is for aliases, such as g
for git
, now
for printing the current time, etc.
Alias conventions:
For an alias that is a one-letter shortcut, we use a naming convention for the file: the letter, an equal sign, and the result. For example, the file g=git.zsh
is the alias that sets g
to run git
.
For an alias that is intended to launch a program, we use a convention of trying probable locations for the tool. For example, for the alias firefox
, we look in order in /opt
(e.g. typical for our custom installs), then on the path, then in the typical macOS location.
Environment program conventions:
$EDITOR
for editing text files, such as vi
or emacs
.
$PAGER
for showing text files, such as more
or less
.
$FINDER
for searching text files, such as grep
or rg
.
$CLIPPER
for copying text to a clipboard, such as xclip
or pbcopy
.
$DATER
for showing dates and times, such as date
or gdate
.
$JUMPER
for moving among directories, such as jump
or jumpdir
.
Date/time format conventions:
We default to nanoseconds precision (not seconds precision), because we use subsecond precision on some of our systems.
We default to UTC timezone and the format "+00:00" (not "Z"), because this maximizes our compatibility with fintech systems and logs.
Clone:
git clone https://github.com/sixarm/sixarm_zsh_config
Move the directories and files as you like, to wherever you want.
For one user, we prefer to put files in a user's configuration directory:
config=${XDG_CONFIG_HOME:-$HOME/.config}
Make directories:
mkdir -p $config/{zshenv.d,zprofile.d,zshrc.d,zlogin.d,zlogout.d}
Copy files:
cp -R sixarm-zsh-config/zshenv.d/* $config/zshenv.d
cp -R sixarm-zsh-config/zprofile.d/* $config/zprofile.d
cp -R sixarm-zsh-config/zshrc.d/* $config/zshrc.d
cp -R sixarm-zsh-config/zlogin.d/* $config/zlogin.d
cp -R sixarm-zsh-config/zlogout.d/* $config/zlogout.d
Add this to the user file .zshenv
:
config=${XDG_CONFIG_HOME:-$HOME/.config}
for file in $config/zshenv.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the user file .zprofile
:
config=${XDG_CONFIG_HOME:-$HOME/.config}
for file in $config/zprofile.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the user file .zshrc
:
config=${XDG_CONFIG_HOME:-$HOME/.config}
for file in $config/zshrc.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the user file .zlogin
:
config=${XDG_CONFIG_HOME:-$HOME/.config}
for file in $config/zlogin.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the user file .zlogout
:
config=${XDG_CONFIG_HOME:-$HOME/.config}
for file in $config/zlogout.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
For the system, we prefer to put files in the system's /etc
directory:
config=/etc
Make directories:
mkdir -p $config/{zshenv.d,zprofile.d,zshrc.d,zlogin.d,zlogout.d}
Copy files:
cp -R sixarm-zsh-config/zshenv.d/* $config/zshenv.d
cp -R sixarm-zsh-config/zprofile.d/* $config/zprofile.d
cp -R sixarm-zsh-config/zshrc.d/* $config/zshrc.d
cp -R sixarm-zsh-config/zlogin.d/* $config/zlogin.d
cp -R sixarm-zsh-config/zlogout.d/* $config/zlogout.d
Add this to the system file zshenv
:
config=/etc
for file in $config/zshenv.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the system file /etc/zprofile
:
config=/etc
for file in $config/zprofile.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the system file zshrc
:
config=/etc
for file in $config/zshrc.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the system file zlogin
:
config=/etc
for file in $config/zlogin.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
Add this to the sytem file zlogout
:
config=/etc
for file in $config/zlogout.d/**/*(.N)
do
[ -x "$file" ] && . "$file"
done
If you have zsh files that you like and that are good for many people, then send them along. We welcome additions, and also welcome pull requests.