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:
- Commands to set up aliases, functions, options, key bindings, for interactive use etc.
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 asg
forgit
,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 setsg
to rungit
. -
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 asvi
oremacs
. -
$PAGER
for showing text files, such asmore
orless
. -
$FINDER
for searching text files, such asgrep
orrg
. -
$CLIPPER
for copying text to a clipboard, such asxclip
orpbcopy
. -
$DATER
for showing dates and times, such asdate
orgdate
. -
$JUMPER
for moving among directories, such asjump
orjumpdir
.
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.