Cheat sheet on zsh

Home

1 zsh

zsh is not to be confused with oh-my-zsh, which is a set of customizations for zsh that I may or may not like. oh-my-zsh is a plugin manager for zsh. It has themes, and just loads a bunch of zsh scripts when you open it.

2 zsh setup

Use usual package manager to install it, if you linux does not have it. As of MacOSX Catalina, zsh has become the default shell, so no install is needed for MacOSX.

2.1 ~/.zshrc

Default run control is ~/.zshrc. But if you export ZDOTDIR=$HOME/.config/zsh then all your .zshrc and other files should reside in ~/.config/zsh

But what tells zsh to look for .zshrc when first booting? The answer is ~/.zshenv 

export ZDOTDIR=$HOME/.config/zsh

I then put ALL my .zsh config files in ~/.config/zsh directory. In that directory my .zshrc file sources the zsh-aliases file as well that is in $HOME/.config/zsh/zsh-aliases and those are being read properly.

2.1.1 ~.zshenv to set ZDOTDIR

This file need only have one line, export ZDOTDIR=$HOME/.config/zsh or even just ZDOTDIR=$HOME/.config/zsh, but I will want this as an environment variable, available to all child processes, so I will use the export in my .zshenv file.

2.2 PS1 in zshrc

Some definitions:

  • % and ) are special characters. To escape them with a % So %% will show a % in your prompt.
  • %M full hostname
  • %m hostname
  • %n username
  • %l TTY device you are using (strips /dev or /dev/tty
  • %y TTY device
  • %d pwd where d is the depth to go to I
  • %~ pwd where ~ is displayed for your home direcdtory
  • %C pwd but only the trailing directory
  • %? return code from previous command
  • %h history line number
  • %D current YY-MM-DD
  • %w current DD
  • %T current time 24H
  • %t current time am/pm
  • %D{string} string can be one of the ones listed below
  • %B bold
  • %b un-bold
  • %U underline
  • %u no underline
  • %S hightlighted
  • %s un-hightlighted
  • %F{colour} change foreground to colour
  • %f reset colour
  • %K{colour} change background to colour (black, red, green, yellow, blue, magenta, cyan, white)
  • %k reset background colour
  • % x
  • % x

2.2.1 %D{string}

%a = Day of week abbreviation
%A = Full day of week name
%w = day of the week (0-6)

%d = day of the month (01-31)

%b = Abbreviated month name
%B = full month name
%m = Month (00-12)

%y = Year (00-99)
%Y = Year (4 digits)

%H = Hour (00-23)
%k = Hour (0-23)
%I = Hour (01-12)
%l = Hour (1-12)

%M = Minute (00-59)

%S = Seconds (00-59)

%p = AM or PM
%P = am or pm

My prompt is currently:

  • PROMPT="%B%{$fg[yellow]%}%d%(?:%{$fg_bold[green]%}[%h]➜:%{$fg_bold[red]%}[%h])

$%{$reset_color"

2.3 zsh colours

zsh has named colours: black, red, green, yellow, blue, magenta, cyan, white zsh has equivalent numbers: 000, 001, 002, 003, 004, 005, 006, 007 in order.

zsh also support #rrggbb. so red = #ff0000, green = #00ff00, blue = #0000ff

red #ff0000
green #00ff00
blue #0000ff
white #ffffff
black #000000
yellow #ffff00
magenta #ff00ff
cyan #00ffff

2.4 wildcard expansion

By default, if you say: 

files=*.log
echo $files

You will see just this *.log

If you then set -o GLOB_SUBST in your zsh, and try the same thing above you will see: 

syslog.log
messages.log
smtp.log
...

2.5 auto completion

I am not sure this is set up. See next section on commands 

# while this is a lot of typing
cd ~/Documents/business/git/check42

# this is much more comfy
cd ~/D/b/g/42<tab>

2.6 auto completion on command options

if you hit the tab after the - option, for example ls -<tab> you will see all the ls options available to you. (like a mini man page summary).

It must be after the - character, otherwise you get normal tab completion.

2.7 auto completion for commands

You can also hit <tab> after any partially entered command, and see all the commands that start with those partially entered strings. This is just like the tradiational <tab> autocompletion available in bash but now also on commands Pretty cool!

To turn this on, include this chunk in your .zshrc file. (located where you have set your $ZDOTDIR says it is). 

# completions
autoload -Uz compinit
zstyle ':completion:*' menu select
# zstyle ':completion::complete:lsof:*' menu yes select
zmodload zsh/complist
# compinit
_comp_options+=(globdots)               # Include hidden files.

autoload -U up-line-or-beginning-search
autoload -U down-line-or-beginning-search
zle -N up-line-or-beginning-search
zle -N down-line-or-beginning-search

# Colors
autoload -Uz colors && colors

2.8 z in place of cd

If you have a directory somewhere deep, with name "webex" you can simply: z webex instead of cd ~/bin/python/bin/webex

You have to load the z plugin for this to work.

2.9 Chris @ Machine git repo

Chris has some good zsh config files on github.com Check them out. I cloned his repo to ~/.config/machine-clone/ i.e.

  • git clone https://github.com/Mach-OS/Machfiles.git machine-clone

2.9.1 zsh plugins

#!/bin/sh

find "$ZDOTDIR/plugins" -type d -exec test -e '{}/.git' ';' -print0 | xargs -I {} -0 git -C {} pull"

2.9.2 zshrc from github

# export ZDOTDIR=$HOME/.config/zsh
# source "$HOME/.config/zsh/.zshrc"
#!/bin/sh
export ZDOTDIR=$HOME/.config/zsh
HISTFILE=~/.zsh_history
setopt appendhistory

# some useful options (man zshoptions)
setopt autocd extendedglob nomatch menucomplete
setopt interactive_comments
stty stop undef         # Disable ctrl-s to freeze terminal.
zle_highlight=('paste:none')

# beeping is annoying
unsetopt BEEP


# completions
autoload -Uz compinit
zstyle ':completion:*' menu select
# zstyle ':completion::complete:lsof:*' menu yes select
zmodload zsh/complist
# compinit
_comp_options+=(globdots)               # Include hidden files.

autoload -U up-line-or-beginning-search
autoload -U down-line-or-beginning-search
zle -N up-line-or-beginning-search
zle -N down-line-or-beginning-search

# Colors
autoload -Uz colors && colors

# Useful Functions
source "$ZDOTDIR/zsh-functions"

# Normal files to source
zsh_add_file "zsh-exports"
zsh_add_file "zsh-vim-mode"
zsh_add_file "zsh-aliases"
zsh_add_file "zsh-prompt"

# Plugins
zsh_add_plugin "zsh-users/zsh-autosuggestions"
zsh_add_plugin "zsh-users/zsh-syntax-highlighting"
zsh_add_plugin "hlissner/zsh-autopair"
zsh_add_completion "esc/conda-zsh-completion" false
# For more plugins: https://github.com/unixorn/awesome-zsh-plugins
# More completions https://github.com/zsh-users/zsh-completions

# Key-bindings
bindkey -s '^o' 'ranger^M'
bindkey -s '^f' 'zi^M'
bindkey -s '^s' 'ncdu^M'
# bindkey -s '^n' 'nvim $(fzf)^M'
# bindkey -s '^v' 'nvim\n'
bindkey -s '^z' 'zi^M'
bindkey '^[[P' delete-char
bindkey "^p" up-line-or-beginning-search # Up
bindkey "^n" down-line-or-beginning-search # Down
bindkey "^k" up-line-or-beginning-search # Up
bindkey "^j" down-line-or-beginning-search # Down
bindkey -r "^u"
bindkey -r "^d"

# FZF 
# TODO update for mac
[ -f /usr/share/fzf/completion.zsh ] && source /usr/share/fzf/completion.zsh
[ -f /usr/share/fzf/key-bindings.zsh ] && source /usr/share/fzf/key-bindings.zsh
[ -f /usr/share/doc/fzf/examples/completion.zsh ] && source /usr/share/doc/fzf/examples/completion.zsh
[ -f /usr/share/doc/fzf/examples/key-bindings.zsh ] && source /usr/share/doc/fzf/examples/key-bindings.zsh
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
[ -f $ZDOTDIR/completion/_fnm ] && fpath+="$ZDOTDIR/completion/"
# export FZF_DEFAULT_COMMAND='rg --hidden -l ""'
compinit

# Edit line in vim with ctrl-e:
autoload edit-command-line; zle -N edit-command-line
# bindkey '^e' edit-command-line

# TODO Remove these
setxkbmap -option caps:escape
xset r rate 210 40

# Speedy keys
xset r rate 210 40

# Environment variables set everywhere
export EDITOR="nvim"
export TERMINAL="alacritty"
export BROWSER="brave"

# For QT Themes
export QT_QPA_PLATFORMTHEME=qt5ct

# remap caps to escape
setxkbmap -option caps:escape
# swap escape and caps
# setxkbmap -option caps:swapescape

2.10 themes

slant looks interesting. Something to try. Also try prompt -p to see what you have available so far.

2.11 hacking oh-my-zsh themes

oh-my-zsh themes are just scripts that you can download from github and then put in your zsh directory and then just source them in your ~/.zshrc file.

When trying them out, you can just source them right from your zsh command prompt. For instance, you can download the gallois.zsh-theme file, then source it.

3 Fonts to display  properly

My emacs font never had a problem displaying the git icon, however both terminal and iterm2 displayed a ? in a box instead of the  character.

3.0.1 Fix

I tried several things, and this worked for me. First I downloaded the hack fonts from www.nerdfonts.com so specifically github.com/ryanoasis hack font.

hack-nerd-fonts-for-terminal.png

Figure 1: Hack Nerd Fonts

I had also used brew to install them, but I think my manually moving the fonts from the above links to ~/LibraryFonts was the actual fix. But for completeness, (and since I won't be doing this again on my Mac, I can't really test this) here is the brew install command:

  • brew install font-hack-nerd-font
  1. Download

    Downloaded the fonts to a temp location.

  2. Move to ~/Library/Fonts

    This resulted in these .ttf files in ~/Library/Fonts

    • Hack-Regular.ttf
    • Hack-Italic.ttf
    • Hack-BoldItalic.ttf
    • Hack-Bold.ttf
    • Hack Regular Nerd Font Complete.ttf
    • Hack Regular Nerd Font Complete Mono.ttf
    • Hack Italic Nerd Font Complete.ttf
    • Hack Italic Nerd Font Complete Mono.ttf
    • Hack Bold Nerd Font Complete.ttf
    • Hack Bold Nerd Font Complete Mono.ttf
    • Hack Bold Italic Nerd Font Complete.ttf
    • Hack Bold Italic Nerd Font Complete Mono.ttf
  3. Add the font to Font Book App

    Then I choose the font Hack Regular Nerd Font Complete Mono 18 in both iterm and terminal.

    I restarted the terminal (and iterm2)

  4. Change the preferences on terminal app and iterm app

    Both were under Profiles/Text/Font

    For terminal this looks like:

    terminal-hack-fonts-preferences.png

    Figure 2: Changing Terminal Font (part A)

    terminal-hack-fonts-preferences-B.png

    Figure 3: Changing Terminal Font (part B)

3.0.2 Failed fixes

Installing several other fonts did NOT work for me. In fact I ended up removing them using the Mac Font Book.app

  • powerline fonts any of them
  • sourcecodepro powerline awesome regular fonts
  • Spacemono
  • DejaVu Sans Mono for Powerline

I also removed all the others fonts that were included in the powerline font downloaded from github.

4 Using zsh

Get help on selecting a prompt with prompt -p (None of which I liked so far)

There were more prompts available that did not show up with just prompt -p Instead, try prompt -l to list them , then prompt -p adam1 if adam1 was one of the listed prompts.

4.1 history

You may be surprised that history only shows the last 15 commands in zsh. This is by design in zsh. So, to show all lines you must use history 1

4.2 Home