Cookbook

Plugin development

In order to develop and load a plugin with Antigen you should configure the plugin as follows:

# Disable antigen's cache to always load latest changes from the plugin
export _ANTIGEN_CACHE_ENABLED=false

# Pass --no-local-clone to antigen's bundle to tell antigen to load the plugin
# from /path/to/plugin rather than cloning it
antigen bundle /path/to/plugin --no-local-clone

# Don't forget to tell antigen that you're done
antigen apply

Use antigen theme in the case you're developing a theme rather than a bundle.

If your bundle do use compinit in some way remember to always refresh your .zcompdump file. The easiest way is to run:

rm ~/.zcompdump*

Static bundle loading

If you need to load antigen faster you may load bundles statically from cache. This way you can avoid loading and running antigen.

Note: This will be unnecessary for 2.x as this will be performed by antigen itself.

Example .zshrc:

# If there is cache available
if [[ -f ${ADOTDIR:-$HOME/.antigen}/.cache/.zcache-payload ]]; then
    # Load bundles statically
    source ${ADOTDIR:-$HOME/.antigen}/.cache/.zcache-payload

    # You will need to call compinit
    autoload -Uz compinit
    compinit -d ${HOME}/.zcompdump
else
    # If there is no cache available do load and execute antigen
    source $ANTIGEN/antigen.zsh

    # I'm using antigen-init here but your usual antigen-bundle,
    # antigen-theme, antigen-apply will work as well
    antigen init $ZSH_CUSTOM/.antigenrc
fi

This way you can greatly improve performance.

Init command

Use this command to load antigen configuration. Example set up:

.zshrc:

source antigen.zsh
antigen init .antigenrc

.antigenrc:

antigen use oh-my-zsh

antigen bundle ...
antigen theme ...

antigen apply

This setup further improves cache performance (~0.02s). One caveat: antigen-init command doesn't look into bundle configuration changes, thus you'll need to use antigen-reset to reload plugins.

Configure compdump location

Use ANTIGEN_COMPDUMPFILE to configure zsh compdump file location:

.zshrc:

export ANTIGEN_COMPDUMPFILE=/path/to/location/.zcompdump

Configure custom default library

Antigen supports Oh-My-Zsh and Prezto by default. So you can easily manage bundles from those libraries, this way:

.antigenrc:

antigen use oh-my-zsh
antigen bundle git-extras
antigen theme agnoster
antigen apply

Both git-extras and agnoster theme are going to be used from Oh-My-Zsh repository. This work for Oh-My-Zsh and Prezto in the same way.

If you have a Oh-My-Zsh or Prezto fork and you naturally will prefer to use this fork instead. With Antigen it's easy to do that, with a simple configuration:

.zshrc

ANTIGEN_DEFAULT_REPO_URL=https://github.com/custom/oh-my-zsh

.antigenrc

antigen bundle git-extras
antigen apply

In this example git-extras will be loaded from custom/oh-my-zsh repository, instead of the canonical one.

You can also use a custom library url as follow:

.antigenrc

antigen use https://github.com/custom/library.git
antigen bundle git
antigen apply

Here, git bundle will be loaded from custom/library library.