zsh Commands

History Search

History size and behaviour go in ~/.zshrc:

HISTSIZE=50000
SAVEHIST=50000
setopt SHARE_HISTORY          # share history across open terminals
setopt HIST_IGNORE_ALL_DUPS   # keep one copy of a repeated command
setopt HIST_IGNORE_SPACE      # commands starting with a space are not saved
setopt EXTENDED_HISTORY       # record a timestamp with each command

# Up/Down search commands starting with what you typed
bindkey '^[[A' history-beginning-search-backward
bindkey '^[[B' history-beginning-search-forward

zsh: corrupt history file /Users/you/.zsh_history means the file has bad bytes in it. Salvage what is readable:

mv ~/.zsh_history ~/.zsh_history_bad
strings ~/.zsh_history_bad > ~/.zsh_history
fc -R ~/.zsh_history

Keyboard Shortcuts

Emacs-style bindings, the default. See the next section for vi mode.

Aliases

Aliases live for one session unless you put them in ~/.zshrc:

echo "alias ll='ls -lah'" >> ~/.zshrc
source ~/.zshrc

An alias cannot take arguments; anything you type is appended to the end. When you need the argument in the middle, write a function instead:

mkcd() { mkdir -p "$1" && cd "$1" }
gclone() { git clone "https://github.com/$1.git" && cd "${1##*/}" }

Completion

zsh's completion system knows flags, hostnames, git branches, and PIDs, but only after you turn it on.

Keybindings and Vi Mode

In vi normal mode: k/j step through history, / searches it, v opens the line in your editor.

Globbing

zsh globbing does what you would otherwise need find for. Recursive ** works out of the box.

setopt extendedglob   # enables ^negation and the ~exclusion operator

For heavier searches (by mtime, with -exec), see the find cheat sheet.

zmv renames in bulk using the same patterns, with -n for a dry run:

autoload -Uz zmv
zmv -n '(*).jpeg' '$1.jpg'      # drop -n to actually rename
zmv -n '(**/)(*).log' '$1$2.txt'
zmv -nW '*.txt' 'backup_*.txt'  # -W uses plain wildcards instead of groups

Arrays

zsh arrays start at 1, not 0, and a bare $a gives every element rather than the first. Both trip up pasted bash code.

Environment and PATH

zsh ties the path array to $PATH, so you can edit it like a list instead of pasting colons.

PATH belongs in ~/.zprofile so it is set once per login instead of growing in every nested shell:

# ~/.zprofile
typeset -U path
path=(/opt/homebrew/bin /opt/homebrew/sbin $path ~/bin)
export PATH

Startup Files

Read in this order. macOS Terminal and iTerm open login shells, so .zprofile and .zshrc both run; most Linux terminals open non-login shells, so only .zshrc runs.

After editing any of them: source ~/.zshrc (or open a new tab).

Prompt

Common escapes: %n user, %m host, %~ directory with ~, %# % or #, %T time, %? last exit code. Most people skip hand-rolling and install powerlevel10k or starship, which come with git status, exit codes, and language versions built in.

Oh My Zsh

A config framework: themes, completion tweaks, and plugins in one install. Everything lives in ~/.zshrc after it is set up.

The git plugin is why most people install it. The aliases you will actually use:

Run alias | grep git to see the full list (150+).

Plugins

The two everyone installs are autosuggestions and syntax highlighting. Neither needs a framework; they are repos you source from ~/.zshrc.

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting ~/.zsh/zsh-syntax-highlighting

# in ~/.zshrc, syntax highlighting must be sourced last
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
source ~/.zsh/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

With Oh My Zsh, clone into $ZSH_CUSTOM/plugins instead and add the names to the plugins=(...) line. If startup gets slow, a manager that lazy-loads (zinit, antidote, zim) is the usual next step, or drop the framework and keep the source lines.

Command Not Found Fixes

zsh: command not found: X means the binary is not on your PATH or is not a binary at all. The pattern is the same for brew, pip, npm, nvm, docker, and code.

Permission Denied

zsh: permission denied: ./deploy.sh is about the file, not about zsh. The shell found it and the kernel refused to run it.

Install and Switch Shells

On Windows there is no native zsh. Install it inside WSL (wsl --install, then sudo apt install zsh) and set it as the default shell in the Linux distro, not in PowerShell.

One-Liners and Substitution

zsh vs bash

Typing commands feels identical, since ls, grep, git and ssh are programs, not shell features. What differs is quoting, arrays and globbing. For bash syntax itself, see the bash cheat sheet.

The three that break a pasted bash snippet:

files="a.txt b.txt"
ls $files      # zsh looks for one file named "a.txt b.txt"; use ${=files} to split

a=(x y z)
echo $a[1]     # zsh prints x; the same array in bash starts at ${a[0]}

ls *.nope      # zsh: "no matches found" and ls never runs; bash passes *.nope to ls

Scripts are unaffected: a #!/bin/bash shebang runs the script in bash whatever your login shell is. Write new scripts for the shell you name in the shebang.

Gotchas

• zsh: no matches found when a URL contains ? or *: zsh globs the argument. Quote it (curl 'https://api.example.com/x?y=1') or setopt no_nomatch.
• # comments do not work at the interactive prompt by default: setopt interactive_comments (Oh My Zsh turns this on for you).
• zsh: event not found on a command containing ! inside double quotes: history expansion fires before anything else. Use single quotes, or setopt no_bang_hist to switch it off.
• zsh: you have suspended jobs when you try to exit: run jobs to see them, fg to finish one, or disown -a to cut them loose. A second exit also works.
• zsh: killed on a Mac binary you downloaded is Gatekeeper, not memory: xattr -d com.apple.quarantine ./tool. On a server it usually is memory, and dmesg | tail will say so.
• Pasted multi-line snippets run line by line as they land. Paste into Ctrl+X Ctrl+E (editor) if you want to review first.
• A new PATH entry in ~/.zshrc only applies to new shells; source ~/.zshrc fixes the current one.
• zsh writes each terminal's history at exit by default; setopt SHARE_HISTORY if you want tabs to see each other's commands live.
• Long remote sessions die with the connection. Run zsh inside tmux on servers so your shell survives a dropped SSH connection.