Skip to main content

♻️ Migration


OMZ shorthand syntax

zi snippet <URL>        # Raw syntax with URL
zi snippet OMZ::<PATH> # Shorthand OMZ:: (
zi snippet OMZL::<PATH> # Shorthand OMZ::lib (
zi snippet OMZT::<PATH> # Shorthand OMZ::themes (
zi snippet OMZP::<PATH> # Shorthand OMZ::plugins (

OMZ library

Importing the clipboard and termsupport from the OMZ library example:

Raw syntax:

zi snippet
zi snippet

OMZ shorthand syntax:

zi snippet OMZ::lib/clipboard.zsh
zi snippet OMZ::lib/termsupport.zsh

OMZL shorthand syntax:

zi snippet OMZL::clipboard.zsh
zi snippet OMZL::termsupport.zsh

Example of more advanced, library loading using subversion:

if (( $+commands[svn] )) {
zi is-snippet has'svn' for svn \
multisrc'${sni[*]}' pick'/dev/null' \
atinit'typeset -gx COMPLETION_WAITING_DOTS=true \
HISTSIZE=290000 SAVEHIST=290000 HISTFILE=${ZSH_CACHE_DIR}/.history;' \
unset sni
} else {
+zi-message "{auto}Subversion not installed!"

OMZ plugins

- plugins=(
- git
- dotenv
- rake
- rbenv
- ruby

+ zi snippet OMZP::git
+ zi snippet OMZP::dotenv
+ zi snippet OMZP::rake
+ zi snippet OMZP::rbenv
+ zi snippet OMZP::ruby

Example of more advanced, conditional turbo loading:

zi is-snippet wait lucid for \
atload"unalias grv g" \
OMZP::{git,sudo,encode64,extract} \
if'[[ -d /opt/google-cloud-sdk ]]' \
OMZP::gcloud \
if'[[ -f /etc/os-release ]] && source /etc/os-release && [[ "$ID" = arch ]]' \
OMZP::archlinux \
if'[[ -d ~/.nvm ]]' \
OMZP::nvm \
if'[[ -d ~/.ssh ]]' \
OMZP::ssh-agent \
if'[[ -d ~/.gnupg ]]' \
OMZP::gpg-agent \
if'[[ "$OSTYPE" = *-gnu ]]' \
OMZP::gnu-utils \
has'pip' \
OMZP::pip \
has'python' \

Bundle the example above to a single file:

zi snippet <some/path/or/url/bundled-snippets.zsh

Use zi ice svn if multiple files require an entire subdirectory.

zi ice svn
zi snippet OMZP::gitfast

zi ice svn
zi snippet OMZP::osx

zi ice svn
zi snippet OMZP::history-substring-search

Use zi ice as"completion" to directly add single file completion snippets.

zi ice as"completion"
zi snippet OMZP::docker/_docker

zi ice as"completion"
zi snippet OMZP::fd/_fd

zi ice as"completion"
zi snippet OMZP::ag/_ag

OMZ themes

Themes are stored in the themes directory and loaded in the background with the simple syntax:


However, Zi doesn't support the ZSH_THEME variable natively.

To use themes created for OMZ requires loading shown below as it would be the same as OMZ does in the background.

Some themes may require additional configuration it can be determined from the theme configuration file.

  • Load git library
  • Load the git plugin
  • Load library dependencies
  • Enable setopt prompt_subst

If any of the above are not in order or missing, the theme will break similar as shown below:


If the Git library is not loaded or loaded in the wrong order, then it may appear similar to the following:

........:1: command not found: git_prompt_status
........:1: command not found: git_prompt_short_sha

If you encounter any issue with the theme, OMZ support libraries are to be loaded

  • If your theme isn't colored when it should, you will want to load theme-and-appearance.zsh

  • If you encounter an error message similar to:

zsh: command not found: ruby_prompt_info

You need to load prompt_info_functions.zsh

All together it looks like this:

zi snippet OMZL::git.zsh
zi snippet OMZP::git
zi snippet OMZL::theme-and-appearance.zsh
zi snippet OMZL::prompt_info_functions.zsh

Then load the prompt:

setopt prompt_subst
zi snippet OMZT::robbyrussell

External theme sample: NicoSantangelo/Alpharized

Load with OMZ:


Load git library from OMZ:

zi snippet OMZL::git.zsh

Load git plugin from OMZ:

zi snippet OMZP::git
zi cdclear -q

Then load the prompt:

setopt prompt_subst
zi light NicoSantangelo/Alpharized


PZT shorthand syntax

zi snippet <URL>        # Raw syntax with URL
zi snippet PZT::<PATH> # Shorthand PZT:: (
zi snippet PZTM::<PATH> # Shorthand PZT::modules/ (

PZT modules

Importing the environment and terminal Prezto modules example:

Raw syntax

zi snippet
zi snippet

PZT shorthand syntax:

zi snippet PZT::<PATH>
zi snippet PZT::modules/environment
zi snippet PZT::modules/terminal

PZTM shorthand syntax:

zi snippet PZTM::<PATH>
zi snippet PZTM::environment
zi snippet PZTM::terminal

Prezto modules:

- zstyle ':prezto:load' pmodule 'git'
- zstyle ':prezto:load' pmodule 'environment' 'terminal'

+ zi snippet PZTM::git
+ zi is-snippet for PZTM::environment PZTM::terminal

Available Prezto modules:

Module nameDescription
archiveProvides functions to list and extract archives.
autosuggestionsIntegrates zsh-autosuggestions plugin into Prezto.
command-not-foundLoads the command-not-found tool on macOS or Debian-based distributions.
completionSets TAB completion and provides additional completions from the zsh-completions.
directorySets directory options and defines directory aliases.
dnfDefines dnf aliases.
dockerDefines docker aliases and functions.
dpkgDefines dpkg aliases and functions.
editorSets key bindings.
emacsEnables Emacs dependency management.
environmentSets general shell options and defines environment variables.
fasdMaintains a frequently used file and directory list for fast access.
gitEnhances the Git by providing aliases, functions and by exposing repository status information to prompts.
gnu-utilityProvides for the interactive use of GNU utilities on non-GNU systems.
gpgProvides for an easier use of GPG by setting up gpg-agent.
haskellEnables local Haskell package installation.
helperProvides helper functions for developing modules.
history-substring-searchIntegrates zsh-history-substring-search into Prezto.
historySets history options and defines history aliases.
homebrewDefines Homebrew aliases.
macportsDefines MacPorts aliases and adds MacPorts directories to path variables.
nodeProvides utility functions for Node.js and loads npm completion.
ocamlInitializes OCaml package management.
osxDefines macOS aliases and functions.
pacmanProvides aliases and functions for the Pacman package manager and frontends.
perlEnables local Perl module installation on macOS and defines aliases.
promptLoads prompt themes.
pythonEnables local Python and local Python package installation.
railsDefines Ruby on Rails aliases.
rsyncDefines rsync aliases.
rubyConfigures Ruby local gem installation, loads version managers, and defines aliases.
screenDefines GNU Screen aliases and provides for auto launching it at start-up.
spectrumProvides for easier use of 256 colors and effects.
sshProvides for an easier use of SSH by setting up ssh-agent.
syntax-highlightingIntegrates zsh-syntax-highlighting into Prezto.
terminalSets terminal window and tab titles.
tmuxDefines tmux aliases and provides for auto launching it at start-up.
utilityDefines general aliases and functions.
wakeonlanThis module provides a wrapper around the wakeonlan tool.
yumDefines yum aliases.

Use zi ice svn if multiple files require an entire subdirectory.

zi ice svn
zi snippet PZTM::docker

zi ice svn
zi snippet PZTM::git

Use zi ice as"null" no *.plugin.zsh, init.zsh, *.zsh-theme* files exist in module directory.

zi ice svn as"null"
zi snippet PZTM::archive

Use zi ice atclone"git clone <repo> <location>" if module have external module.

zi ice svn blockf \
atclone"git clone --recursive external"
zi snippet PZTM::completion

Use blockf to prevent any unnecessary additions to fpath, as Zi manages fpath.


What is zstyle?



Load OMZ library

- zgen oh-my-zsh

+ zi snippet OMZL::<ANY OF THEM>

Load OMZ plugins

- zgen oh-my-zsh <PATH>

+ zi snippet OMZP::<PATH>

Load Prezto modules

- zgen prezto <module name>

+ zi snippet PZTM::<module name>

Load repositories as prezto plugins:

- zgen pmodule <reponame> <branch>

+ zi ice ver"<branch>"
+ zi load <repo/plugin>

Summarized Zgen


For the location: refer src, pick, multisrc ice-modifier.

- zgen load <repo> [location] [branch]

+ zi ice ver"[branch]"
+ zi load <repo>

Zplug Basics

- zplug <repo/plugin>, tag1:<option1>, tag2:<option2>

+ zi ice tag1"<option1>" tag2"<option2>"
+ zi load <repo/plugin>

Tag comparison

  • as => as
  • use => pick, src, multisrc
  • ignore => None
  • from => from
  • at => ver
  • rename-to => mv, cp
  • dir => Selection(pick, …) with rename
  • if => if
  • hook-build => atclone, atpull
  • hook-load => atload
  • frozen => None
  • on => None
  • defer => wait
  • lazy => autoload
  • depth => depth