Zsh

Zsh.md

Config files

To configure Zsh for your user’s session, you can use the following files:

• $ZDOTDIR/.zshenv
• $ZDOTDIR/.zprofile
• $ZDOTDIR/.zshrc
• $ZDOTDIR/.zlogin
• $ZDOTDIR/.zlogout

By default, Zsh will try to find the user’s configuration files in the $HOME directory. You can change it by setting the environment variable $ZDOTDIR.

Zsh read these files in the following order:

• .zshenv - Should only contain user’s environment variables.
• .zprofile - Can be used to execute commands just after logging in.
• .zshrc - Should be used for the shell configuration and for executing commands.
• .zlogin - Same purpose than .zprofile, but read just after .zshrc.
• .zlogout - Can be used to execute commands when a shell exit.

For example, you can have all your configuration files in $HOME/.config. To do so:

• Set the variable $XDG_CONFIG_HOME as following: export XDG_CONFIG_HOME="$HOME/.config".
• Set the environment variable $ZDOTDIR: export ZDOTDIR="$XDG_CONFIG_HOME/zsh".
• Put the file .zshrc in the $ZDOTDIR directory.

Most software will use the path in $XDG_CONFIG_HOME to install their own config files. As a result, you’ll have a clean $HOME directory. Unfortunately, the file .zshenv needs to be in your home directory. It’s where you’ll set $ZDOTDIR. Then, every file read after .zshenv can go into your $ZDOTDIR directory.

Basic Configuration

Environment variables

As we saw, you can set the environment variables you need for your user’s session in the file $HOME/.zshenv. This file should only define environment variables.

For example, you can set up the XDG Base directory there, as seen above:

export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$XDG_CONFIG_HOME/local/share"
export XDG_CACHE_HOME="$XDG_CONFIG_HOME/cache"

You can as well make sure that any program requiring a text editor use your favorite one:

export EDITOR="vim"
export VISUAL="vim"

You can set some Zsh environment variables, too:

export ZDOTDIR="$XDG_CONFIG_HOME/zsh"

export HISTFILE="$ZDOTDIR/.zhistory"    # History filepath
export HISTSIZE=10000                   # Maximum events for internal history
export SAVEHIST=10000                   # Maximum events in history file

I already explained the first line. For the other ones, they will:

• Store your command line history in the file .zhistory.
• Allows you to have a history of 10000 entries maximum.

Aliases

Aliases are crucial to improve your efficiency. I like to have my aliases in one separate file (called, surprisingly, aliases), and I source it in my .zshrc:

source /path/to/my/aliases

Default Aliases (with oh-my-zsh)

Alias	Signification
alias	List all aliases
..	cd ..
...	cd ../..
....	cd ../../..
.....	cd ../../../..
/	cd /
~	cd ~
cd +n	Switch to directory number n from the directory stacks dirs -v
1	cd -
2	cd -2
3	cd -3
4	cd -4
5	cd -5
6	cd -6
7	cd -7
8	cd -8
9	cd -9
md	mkdir -p: create a full directory path
rd	rmdir
d	dirs -v: List last used directories
Ctrl-_	Undo
Ctrl-@	Set mark command
Ctrl-a	Beginning of line
Ctrl-b	Backward char
Ctrl-d	Delete char
Ctrl-e	End of line
Ctrl-f	Forward char
Ctrl-g	Send break
Ctrl-h	Backward delete char
Ctrl-j	Accept line
Ctrl-k	Kill line
Ctrl-l	Clear screen
Ctrl-m	Accept line
Ctrl-n	Down line (or history)
Ctrl-o	Accept line and down history
Ctrl-p	Up line (or history)
Ctrl-q	Push line
Ctrl-r	History search
Ctrl-s	History incremental search forward
Ctrl-t	File search
Ctrl-u	Kill whole line
Ctrl-v	Quoted insert
Ctrl-w	Backward kill word
Ctrl-x+Ctrl-e	Edit command line in vim
Ctrl-x+Ctrl-x	Exchange point and mark
Ctrl-x+c	Correct word
Ctrl-x+m	Most recent file
Ctrl-x+r	History incremental search backward
Ctrl-x+s	History incremental search forward
Ctrl-Alt-h	Backward kill word
Alt-'	Quote line
Alt-a	Accept and hold
Alt-b	Backward word
Alt-c	Capitalize word
Alt-f	Forward word
Alt-h	Run help
Alt-l	Run command ls
Alt-p	History search backward
Alt-q	Push line
Alt-t	Transpose words
Tmux
ta	tmux attach -t
tad	tmux attach -d -t
ts	tmux new-session -s
tl	tmux list-sessions
tksv	tmux kill-server
tkss	tmux kill-server -t

Zsh functions (with oh-my-zsh)

Function	Signification
take	Create a new directory and change to it, will create intermediate directories as required
x/extract	Extract an archive
zsh_stats	Get a list of the top 20 commands and how many times they have been run
upgrade_oh_my_zsh	Upgrade Oh-my-zsh
uninstall_oh_my_zsh	Uninstall Oh-my-zsh
alias_value	Get the value of an alias
omz_urlencode	URL-encode a string (RFC 2396)
omz_urldecode	URL-decode a string (RFC 2396)

Zsh Options

You can set or unset many Zsh options using setopt or unsetopt

Zsh Completion System

The completion system of Zsh is one of its bigger strength, compared to other shells.

To initialize the completion for the current Zsh session, you’ll need to call the function compinit. More precisely, you’ll need to add this in your zshrc:

autoload -Uz compinit; compinit

The autoload command load a file containing shell commands. To find this file, Zsh will look in the directories of the Zsh file search path, defined in the variable $fpath, and search a file called compinit. When compinit is found, its content will be loaded as a function. The function name will be the name of the file. You can then call this function like any other shell function.

Why using autoload, and not sourcing the file by doing source ~/path/of/compinit?

• It avoids name conflicts if you have an executable with the same name.
• It doesn’t expand aliases thanks to the -U option.
• It will load the function only when it’s needed (lazy-loading). It comes in handy to speed up Zsh startup. The -z option tells Zsh that your function is written using "Zsh style". I’m not sure what’s the "Zsh style", but it’s an idiomatic way to autoload functions.

Other Sources

• zstyle doc

Very useful Gist, thanks for this. I have a note: you can set $ZDOTDIR in .xprofile which will set the config dir at the beginning of the X user session. This makes it possible to move .zshenv to $ZDOTDIR.

@Eagle-E If I have no X server run, I think this option won't take functionality. Is this true?

@LittleNewton true, my comment work for your case. You need to find what config files are read/executed when you login to your account, if you set .ZDOTDIR in there, you should be able to get the same result.