Cookbook

Plugin development

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

# 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 $ANTIGEN_COMPDUMP

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 each time you shell starts.

Note: This will be unnecessary for 2.x (current develop) 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. It's unnecessary on Antigen v2 and above as Antigen do lazy-load itself and uses cache when available, plus compiling cache as well.

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

Note: On Antigen v2 and above this configuration is ANTIGEN_COMPDUMP.

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.

Adding Antigen to your dotfiles

If you already have a dotfiles repo you may add Antigen to it as a submodule, as to be able to update it via git.

Add it to your dotfiles repository, in this example located at ~/.dotfiles:

cd ~/.dotfiles
git submodule add https://github.com/zsh-users/antigen.git antigen

Configure your .zshrc file:

ANTIGEN_PATH=~/.dotfiles
source $ANTIGEN_PATH/antigen/antigen.zsh

In order to update antigen do the following:

cd ~/.dotfiles/antigen
git pull