How do I use Oh-My-Zsh with antidote?

[mattmc3]

If you want to use Oh-My-Zsh with antidote, how would you do that?

[mattmc3]

You can use Oh-My-Zsh (OMZ) plugins just like any other plugin with the help of antidote's path: annotation. Antidote doesn't treat OMZ as special, so it behaves the same as any other bundle.

Depending on what plugins you use, this might require you to do some extra setup since OMZ plugins don't expect to be loaded outside of OMZ.

For example, many OMZ plugins will require you to bundle OMZ's 'lib' directory before using them. (If you are an advanced user, you may be able get away with bundling only the parts of lib you need, which for some plugins is nothing).

You may find you also need to set some OMZ specific variables from oh-my-zsh.sh in your .zshrc in order for OMZ to work properly. Be sure to set these before calling antidote load or sourcing your antidote static file.

For example, here's what your .zshrc and your .zsh_plugins.txt might look like when using OMZ:

.zshrc

# prep antidote
source /path/to/antidote.zsh

# set omz variables
ZSH=$(antidote path ohmyzsh/ohmyzsh)
ZSH_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/oh-my-zsh"
[[ -d $ZSH_CACHE_DIR ]] || mkdir -p $ZSH_CACHE_DIR

# load antidote
antidote load

.zsh_plugins.txt

# OMZ has a lot of dependancies on its lib directory.
# Load everything in path:lib before loading any plugins
ohmyzsh/ohmyzsh path:lib

# Now, many plugins or themes should work fine
ohmyzsh/ohmyzsh path:plugins/git
ohmyzsh/ohmyzsh path:plugins/extract
ohmyzsh/ohmyzsh path:plugins/magic-enter
ohmyzsh/ohmyzsh path:plugins/fancy-ctrl-z
ohmyzsh/ohmyzsh path:themes/robbyrussell.zsh-theme

[LuckyWindsck]

I just read through the source code of $ZSH/oh-my-zsh.sh, and here is a complete guide of what's going on inside oh-my-zsh.sh:

TL;DR

Workaround example

Modify from the code above, credit to @mattmc3.

.zshrc

# Prepare antidote
source /path/to/antidote.zsh

# Set omz variables
# Check Oh My Zsh Wiki for how to set these variables.
# https://github.com/ohmyzsh/ohmyzsh/wiki/Settings
ZSH=$(antidote path ohmyzsh/ohmyzsh)
ZSH_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/oh-my-zsh"
[[ -d $ZSH_CACHE_DIR ]] || mkdir -p $ZSH_CACHE_DIR

# Uncomment the following 2 lines if you are using plugin that accesses "$ZSH_CACHE_DIR/completions".
# mkdir -p "$ZSH_CACHE_DIR/completions"
# (( ${fpath[(Ie)"$ZSH_CACHE_DIR/completions"]} )) || fpath=("$ZSH_CACHE_DIR/completions" $fpath)

# Load antidote
antidote load

# Uncomment the following lines if you want fancy completion colors.
# Make sure you enable zsh completion system beforehand
# [[ -z "$LS_COLORS" ]] || zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"

.zsh_plugins.txt

# Enabling zsh completion system
# If you want to enable zsh completion system, you need to make sure the order of loading plugin is correct.
# Check the following antidote discussion for how to order completion plugins.
# https://github.com/mattmc3/antidote/discussions/74

# OMZ has a lot of dependancies on its lib directory.
# Load everything in path:lib before loading any plugins
ohmyzsh/ohmyzsh path:lib
# Or selectively load libs if you are sure what you are doing
# ohmyzsh/ohmyzsh path:lib/theme-and-appearance.zsh

# Now, many plugins or themes should work fine
ohmyzsh/ohmyzsh path:plugins/git
ohmyzsh/ohmyzsh path:plugins/extract
ohmyzsh/ohmyzsh path:plugins/magic-enter
ohmyzsh/ohmyzsh path:plugins/fancy-ctrl-z
ohmyzsh/ohmyzsh path:themes/robbyrussell.zsh-theme

Before initializing Oh My Zsh

This part is what you MUST have done before calling antidote load or sourcing your antidote static file.

1. Protect against non-zsh execution of Oh My Zsh (use POSIX syntax here)

This is UNNECESSARY as long as you use antidote in your zsh startup files (e.g. .zshrc).

See corresponding code snippet

Source

# Protect against non-zsh execution of Oh My Zsh (use POSIX syntax here)
[ -n "$ZSH_VERSION" ] || {
  # ANSI formatting function (\033[<code>m)
  # 0: reset, 1: bold, 4: underline, 22: no bold, 24: no underline, 31: red, 33: yellow
  omz_f() {
    [ $# -gt 0 ] || return
    IFS=";" printf "\033[%sm" $*
  }
  # If stdout is not a terminal ignore all formatting
  [ -t 1 ] || omz_f() { :; }

  omz_ptree() {
    # Get process tree of the current process
    pid=$$; pids="$pid"
    while [ ${pid-0} -ne 1 ] && ppid=$(ps -e -o pid,ppid | awk "\$1 == $pid { print \$2 }"); do
      pids="$pids $pid"; pid=$ppid
    done

    # Show process tree
    case "$(uname)" in
    Linux) ps -o ppid,pid,command -f -p $pids 2>/dev/null ;;
    Darwin|*) ps -o ppid,pid,command -p $pids 2>/dev/null ;;
    esac

    # If ps command failed, try Busybox ps
    [ $? -eq 0 ] || ps -o ppid,pid,comm | awk "NR == 1 || index(\"$pids\", \$2) != 0"
  }

  {
    shell=$(ps -o pid,comm | awk "\$1 == $$ { print \$2 }")
    printf "$(omz_f 1 31)Error:$(omz_f 22) Oh My Zsh can't be loaded from: $(omz_f 1)${shell}$(omz_f 22). "
    printf "You need to run $(omz_f 1)zsh$(omz_f 22) instead.$(omz_f 0)\n"
    printf "$(omz_f 33)Here's the process tree:$(omz_f 22)\n\n"
    omz_ptree
    printf "$(omz_f 0)\n"
  } >&2

  return 1
}

2. Define $ZSH, $ZSH_CACHE_DIR, and make sure $ZSH_CACHE_DIR exists

MAKE SURE to set these before calling antidote load or sourcing your antidote static file. Follow Oh My Zsh Wiki to set these variables.

See corresponding code snippet

Source

# If ZSH is not defined, use the current script's directory.
[[ -z "$ZSH" ]] && export ZSH="${${(%):-%x}:a:h}"

# Set ZSH_CACHE_DIR to the path where cache files should be created
# or else we will use the default cache/
if [[ -z "$ZSH_CACHE_DIR" ]]; then
  ZSH_CACHE_DIR="$ZSH/cache"
fi

# Make sure $ZSH_CACHE_DIR is writable, otherwise use a directory in $HOME
if [[ ! -w "$ZSH_CACHE_DIR" ]]; then
  ZSH_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/oh-my-zsh"
fi

3. Create $ZSH_CACHE_DIR/completions directory and add to $fpath

Some plugins use this directory to save completions. So MAKE SURE you create this directory if you are using any of those plugins.

See corresponding code snippet

Source

# Create cache and completions dir and add to $fpath
mkdir -p "$ZSH_CACHE_DIR/completions"
(( ${fpath[(Ie)"$ZSH_CACHE_DIR/completions"]} )) || fpath=("$ZSH_CACHE_DIR/completions" $fpath)

4. Auto update Oh My Zsh

This is UNNECESSARY since we are using antidote, we should antidote update --bundles manually. Or you can write a script to automate update.

See corresponding code snippet

Source

# Check for updates on initial load...
source "$ZSH/tools/check_for_upgrade.sh"

Initializing Oh My Zsh

1. Add "$ZSH/functions" & "$ZSH/completions" to $path

This might be UNNECESSARY, because both of these 2 directories no longer exist in $ZSH, and this PR comment said:

It's a remnant of past times. It'll probably be removed or it'll be used for something, it's not yet clear.

See corresponding code snippet

Source

# add a function path
fpath=("$ZSH/functions" "$ZSH/completions" $fpath)

2. Initialize zsh completion system

Basically Oh My Zsh does the following 4 steps to enable zsh completion system:

1. Autoload functions that will be called below
2. Define $ZSH_CUSTOM
3. Add all defined plugins to $fpath, before running compinit
4. Call compinit & zrecompile

For antidote, we can just follow this discussion (#74) or specifically this comment to enable zsh completions in correct order.

For more detail about zsh completion system.

According to the documentation of zsh, 20.2.2 Autoloaded files:

When compinit is run, it searches all such files accessible via fpath/FPATH and reads the first line of each of them. This line should contain one of the tags described below. Files whose first line does not start with one of these tags are not considered to be part of the completion system and will not be treated specially.

If I understand correctly, the correct steps to initialize the zsh completion system is:

1. Add the directory containing completion files into $fpath.
2. Use the command autoload -Uz compinit load compinit.
3. Use the command compinit properly to initialize the zsh completion system.
4. (Optional) use other commands for completion system, such as compdef.

2.1. Autoload functions that will be called below

1. compaudit is used in lib/compfix.zsh and lib/diagnostics.zsh
2. compinit is used to initialize completion for the current session
3. zrecompile is ued to compile completion system dumpfile.

You SHOULD determined whether to autoload these functions by yourself.

See corresponding code snippet

Source

# Load all stock functions (from $fpath files) called below.
autoload -U compaudit compinit zrecompile

2.2. Define $ZSH_CUSTOM

This is UNNECESSARY since we are using antidote to manage all custom scripts including plugins, configs, and themes.

See corresponding code snippet

Source

# Set ZSH_CUSTOM to the path where your custom config files
# and plugins exists, or else we will use the default custom/
if [[ -z "$ZSH_CUSTOM" ]]; then
    ZSH_CUSTOM="$ZSH/custom"
fi

2.3. Add all defined plugins to $fpath, before running compinit

This is UNNECESSARY to do it manually since we are using antidote to manage plugins. We just need to use a correct order to load completion plugin as mentioned above.

See corresponding code snippet

Source

is_plugin() {
  local base_dir=$1
  local name=$2
  builtin test -f $base_dir/plugins/$name/$name.plugin.zsh \
    || builtin test -f $base_dir/plugins/$name/_$name
}

# Add all defined plugins to fpath. This must be done
# before running compinit.
for plugin ($plugins); do
  if is_plugin "$ZSH_CUSTOM" "$plugin"; then
    fpath=("$ZSH_CUSTOM/plugins/$plugin" $fpath)
  elif is_plugin "$ZSH" "$plugin"; then
    fpath=("$ZSH/plugins/$plugin" $fpath)
  else
    echo "[oh-my-zsh] plugin '$plugin' not found"
  fi
done

2.4. Call compinit & zrecompile

This can be done either Manually or by USING A COMPLETION PLUGINS that does this for you. See the discussion mentioned above.

See corresponding code snippet

Source

  # Figure out the SHORT hostname
if [[ "$OSTYPE" = darwin* ]]; then
  # macOS's $HOST changes with dhcp, etc. Use ComputerName if possible.
  SHORT_HOST=$(scutil --get ComputerName 2>/dev/null) || SHORT_HOST="${HOST/.*/}"
else
  SHORT_HOST="${HOST/.*/}"
fi

# Save the location of the current completion dump file.
if [[ -z "$ZSH_COMPDUMP" ]]; then
  ZSH_COMPDUMP="${ZDOTDIR:-$HOME}/.zcompdump-${SHORT_HOST}-${ZSH_VERSION}"
fi

# Construct zcompdump OMZ metadata
zcompdump_revision="#omz revision: $(builtin cd -q "$ZSH"; git rev-parse HEAD 2>/dev/null)"
zcompdump_fpath="#omz fpath: $fpath"

# Delete the zcompdump file if OMZ zcompdump metadata changed
if ! command grep -q -Fx "$zcompdump_revision" "$ZSH_COMPDUMP" 2>/dev/null \
  || ! command grep -q -Fx "$zcompdump_fpath" "$ZSH_COMPDUMP" 2>/dev/null; then
  command rm -f "$ZSH_COMPDUMP"
  zcompdump_refresh=1
fi

if [[ "$ZSH_DISABLE_COMPFIX" != true ]]; then
  source "$ZSH/lib/compfix.zsh"
  # Load only from secure directories
  compinit -i -d "$ZSH_COMPDUMP"
  # If completion insecurities exist, warn the user
  handle_completion_insecurities &|
else
  # If the user wants it, load from all found directories
  compinit -u -d "$ZSH_COMPDUMP"
fi

# Append zcompdump metadata if missing
if (( $zcompdump_refresh )) \
  || ! command grep -q -Fx "$zcompdump_revision" "$ZSH_COMPDUMP" 2>/dev/null; then
  # Use `tee` in case the $ZSH_COMPDUMP filename is invalid, to silence the error
  # See https://github.com/ohmyzsh/ohmyzsh/commit/dd1a7269#commitcomment-39003489
  tee -a "$ZSH_COMPDUMP" &>/dev/null <<EOF

$zcompdump_revision
$zcompdump_fpath
EOF
fi
unset zcompdump_revision zcompdump_fpath zcompdump_refresh

# zcompile the completion dump file if the .zwc is older or missing.
if command mkdir "${ZSH_COMPDUMP}.lock" 2>/dev/null; then
  zrecompile -q -p "$ZSH_COMPDUMP"
  command rm -rf "$ZSH_COMPDUMP.zwc.old" "${ZSH_COMPDUMP}.lock"
fi

3. Source Oh My Zsh libs, plugins, custom configs, and theme.

Basically Oh My Zsh does the following things in this part:

1. Define _omz_source function
2. Source Oh My Zsh libs
3. Source plugins
4. Source custom configs
5. Source theme

For antidote, we can safely load all of them in your bundle file, as long as you don't want to skip aliases. If you want to skip default Oh My Zsh aliases or plugin aliases, you might want to check the implementation of the _omz_source function, or simply choose to not loading them.

3.1. Define _omz_source function

_omz_source function uses zstyle to determine whether to skip aliases or not.

See corresponding code snippet

Source

_omz_source() {
  local context filepath="$1"

  # Construct zstyle context based on path
  case "$filepath" in
  lib/*) context="lib:${filepath:t:r}" ;;         # :t = lib_name.zsh, :r = lib_name
  plugins/*) context="plugins:${filepath:h:t}" ;; # :h = plugins/plugin_name, :t = plugin_name
  esac

  local disable_aliases=0
  zstyle -T ":omz:${context}" aliases || disable_aliases=1

  # Back up alias names prior to sourcing
  local -A aliases_pre galiases_pre
  if (( disable_aliases )); then
    aliases_pre=("${(@kv)aliases}")
    galiases_pre=("${(@kv)galiases}")
  fi

  # Source file from $ZSH_CUSTOM if it exists, otherwise from $ZSH
  if [[ -f "$ZSH_CUSTOM/$filepath" ]]; then
    source "$ZSH_CUSTOM/$filepath"
  elif [[ -f "$ZSH/$filepath" ]]; then
    source "$ZSH/$filepath"
  fi

  # Unset all aliases that don't appear in the backed up list of aliases
  if (( disable_aliases )); then
    if (( #aliases_pre )); then
      aliases=("${(@kv)aliases_pre}")
    else
      (( #aliases )) && unalias "${(@k)aliases}"
    fi
    if (( #galiases_pre )); then
      galiases=("${(@kv)galiases_pre}")
    else
      (( #galiases )) && unalias "${(@k)galiases}"
    fi
  fi
}

3.2. Source Oh My Zsh libs

You could load all libs with "ohmyzsh/ohmyzsh path:lib", or choose the lib you want like "ohmyzsh/ohmyzsh path:lib/theme-and-appearance.zsh".

See corresponding code snippet

Source

# Load all of the config files in ~/oh-my-zsh that end in .zsh
# TIP: Add files you don't want in git to .gitignore
for config_file ("$ZSH"/lib/*.zsh); do
  _omz_source "lib/${config_file:t}"
done
unset custom_config_file

3.3. Source plugins

You could load an Oh My Zsh plugin in this way: "ohmyzsh/ohmyzsh path:plugins/git".

See corresponding code snippet

Source

# Load all of the plugins that were defined in ~/.zshrc
for plugin ($plugins); do
  _omz_source "plugins/$plugin/$plugin.plugin.zsh"
done
unset plugin

3.4. Source custom configs

You could load your custom configs like how you load other plugins. If you want to source a local scripts, check this discussion (#75).

See corresponding code snippet

Source

# Load all of your custom configurations from custom/
for config_file ("$ZSH_CUSTOM"/*.zsh(N)); do
  source "$config_file"
done
unset config_file

3.5. Source theme

You could load an Oh My Zsh plugin in this way: "ohmyzsh/ohmyzsh path:path:themes/robbyrussell.zsh-theme".

See corresponding code snippet

Source

# Load the theme
is_theme() {
  local base_dir=$1
  local name=$2
  builtin test -f $base_dir/$name.zsh-theme
}

if [[ -n "$ZSH_THEME" ]]; then
  if is_theme "$ZSH_CUSTOM" "$ZSH_THEME"; then
    source "$ZSH_CUSTOM/$ZSH_THEME.zsh-theme"
  elif is_theme "$ZSH_CUSTOM/themes" "$ZSH_THEME"; then
    source "$ZSH_CUSTOM/themes/$ZSH_THEME.zsh-theme"
  elif is_theme "$ZSH/themes" "$ZSH_THEME"; then
    source "$ZSH/themes/$ZSH_THEME.zsh-theme"
  else
    echo "[oh-my-zsh] theme '$ZSH_THEME' not found"
  fi
fi

4. Set completion colors to be the same as ls, after theme has been loaded

lib/theme-and-appearance.zsh set the default $LS_COLORS, and other themes might override its value.
So if you want to set fancy completion colors, MAKE SURE to run it after you source the theme-and-appearance lib or your theme.

Check the documentation of zsh, 20.3.3 Standard Styles, for more information about list-colors.

See corresponding code snippet

Source

[[ -z "$LS_COLORS" ]] || zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"

[mattmc3]

Amazing! Thank you @LuckyWindsck!

[mattmc3]

As antidote has matured and its user base has grown, I decided that the problem of using Oh-My-Zsh with antidote needed a better solution for its users than asking people to add a bunch of manual configuration themselves. As of June 2024, the recommended way to use OMZ with antidote is to include the brand new getantidote/use-omz plugin at the top of your .zsh_plugins.txt file.

This plugin resolves all the dependencies OMZ has on itself when using its subplugins a la carte. It's a lightweight script that retains antidote's obsession with speed. There's also getantidote/use-prezto which does a similar dependency resolution for Prezto users wanting to use its submodules.

You are welcome to continue to do all the work yourself as @LuckyWindsck describes if you prefer - use-omz is not strictly required, but it is highly recommended and will be the supported path forward for using OMZ with antidote.

[AlecRust]

This is brilliant 😍 thank you!

One thing I noticed is the example .zsh_plugins.txt file still contains this:

# Let's go ahead and use all of Oh My Zsh's lib directory.
ohmyzsh/ohmyzsh path:lib

It's not clear to me if this is a requirement or not for OMZ to function, maybe the comment could be clarified?

I guess with the new use-omz I would have expected to only need to list OMZ plugins in .zsh_plugins.txt, not also the OMZ lib?

[mattmc3]

Great question. The short answer is no, you do NOT need to explicitly load all of lib, or really any of lib. If you use getantidote/use-omz, it is really clever, and knows all about lib and will actually try to lazy-load things as needed when you use OMZ plugins that require things from lib. So, in general, you can skip lib or load individual lib files you know you need. Yea!

HOWEVER - there are a few caveats.

First, Zsh has some really bad defaults out of the box. zstyles for completions aren't set. History variables like HISTSIZE and SAVEHIST are set to inappropriately tiny values. Expected keybindings are missing. Useful Zsh setopt values aren't set. Builtins like ls and grep are missing colorizers and other useful flags.

OMZ's lib does a whole lot to improve the overall Zsh experience. But, you can also accomplish all that by finding other plugins. (belak/zsh-utils is a great alternative option!) For most users used to OMZ or for newbies though, I highly recommend just keeping lib - it's overall much easier.

Second, OMZ is a very dynamic project I have absolutely no control over. What works today might break tomorrow. So if some new dependency in lib is introduced, use-omz may miss it - at least for the short term. If that happens, submit an issue and I'll try to fix! PRs also welcome. If you load all of lib with antidote, you avoid all that risk of future breakage.

Ultimately, I want the choice to be the user's, so use-omz doesn't assume you want lib, but if it's needed it will load.

Hope that helps!

[seakros]

@mattmc3 Came across this and just wanted to clarify this point.

Having ohmyzsh/ohmyzsh path:lib in the zsh_plugins.txt file effectively loads up the default terminal improvements that oh-my-zsh brings to zsh, correct? Core improvements (of sorts) including things such as completion, history scrolling, colorizing - everything except the prompt and any plugins effectively. If you don't have that line, and instead only have a list of oh-my-zsh plugins, it would only load the functionality of those, right?

I'm just relating this to a different issue I came across where a user was trying to get completion to work without oh-my-zsh. belak/zsh-utils also didn't work for me so I deferred back to oh-my-zsh's lib in my zsh_plugins.txt file, but ideally want to strip back my dependencies on it.

Also, thank you for working on this. It is much appreciated and valuable plugin manager!

[mattmc3]

Having ohmyzsh/ohmyzsh path:lib in the zsh_plugins.txt file effectively loads up the default terminal improvements that oh-my-zsh brings to zsh, correct?

Correct. OMZ plugins often assume that lib has been loaded, and will break in weird ways if it's not there.

including things such as completion

No, strangely. Completion is actually handled in oh-my-zsh.sh, not in lib. That can be a big problem if people don't realize that and don't account for that in their config.

If you don't have that line, and instead only have a list of oh-my-zsh plugins, it would only load the functionality of those, right?

Correct. But as I mentioned before, many OMZ plugins don't always function as stand-alones. This is why I built and highly recommend using getantidote/use-omz if you use any OMZ plugins. It handles a few important use-cases:

1. It lets you use explicitly use all, some, or nothing from lib. It will just lazy load whenever elements of lib are needed whenever you use an OMZ plugin. That means you never have to think about what to include from lib if you don't want to.
2. It supports OMZ themes if you want to use them
3. It initializes completions for you, and sets other variables and stuff that happen in oh-my-zsh.sh

I'm just relating this to a different issue...

If you don't want to use any of Oh-My-Zsh's plugins and want to get completions to work, I would recommend giving mattmc3/ez-compinit a try for completions. If you want a full featured alternative to OMZ's lib, you can mix-and-match any of the utility plugins in belak/zsh-utils or mattmc3/zephyr.