Development

When making changes, edit the files in src/. Do not directly edit bin/antigen.zsh as that file is generated automatically. Run make to regenerate it.

Configuration

Use configure to set up build flags, such as enable or disabling extensions:

./configure [--enable|--disable][debug|extensions|lock|parallel|cache|defer|completion]

Extensions

Antigen uses an extension/hook system to provide extensibillity. Extensions can hook on different parts on the Antigen workflow at run-time being able to log/process arguments.

Most functionallity is built with this system such as cache and parallelism.

The system is located at src/ext/ext.zsh, the extensions are located at src/ext/*.zsh.

Running the tests

All the tests are in the tests folder and are run using the [cram][] test system, to install required dependencies use:

sudo make install-deps

Note: You'll need to install dependencies only if you are running without Docker.

With that you can run the tests as:

make tests

By default it will run tests using [Docker][docker] with images from [DockerHub][dockerhub] using zsh version 5.3. You can customize which Docker image it runs against as follows:

make tests CONTAINER_IMAGE=docker-hub/image-name ZSH_VERSION=

Where $CONTAINER_IMAGE is a Docker Hub image name. By default desyncr/zsh-docker-zsh-5.3. If you only need to test against an specific zsh version do as follows:

make tests ZSH_VERSION=zsh-5.0.0 

Docker version used is 17.03.1-ce.

You may as well run tests locally without Docker. Use:

make tests USE_CONTAINER=no

If you are making a feature addition, I'd really appreciate if you can add a test for your feature. Even if you can add a test for an existing feature, that would be great as the tests are currently seriously lagging behind the full functionality of Antigen.

Notes on writing plugins

Most shell utilities/plugins are made up of just one file. For a plugin called awesomeness, create a awesomeness.plugin.zsh and code away.

That said, even if you write a single file as a .sh file with the goodness you want to create, Antigen will work just fine with it. The *.plugin.zsh way is widely used because of the [oh-my-zsh][] project.

If you want to know how Antigen loads the plugins, do continue.

Firstly, Antigen looks for a *.plugin.zsh file in the plugin directory. If present, it will source only this script. Nothing else is sourced. This is for oh-my-zsh style plugins.

Secondly, it looks for a init.zsh file in the plugin directory. If present, Prezto will attempt to load the plugin with pmodload, removing "modules/" from the beginning of the plugin path if present. If pmodload is not available, Antigen will source only init.zsh and nothing else. This is for Prezto-style modules.

Otherwise, it looks for *.zsh files and if there are any, all of them are sourced. The order in which they are sourced is not currently defined. Please don't rely on this order. Nothing else is sourced after all the *.zsh scripts.

If no *.zsh files are present, it finally looks for any *.sh files and sources all of them. Again, the order in which they are sourced in not currently defined.

No matter which (or none) of the above happen to be sourced, this plugin directory is added to the zsh's function path ($fpath) so that any completions in it are loaded.

One exception to this rule is that if this plugin is a theme. In which case the theme script is just sourced and nothing else is done. Not even adding to $fpath.

A note on external zsh plugins

Antigen downloads zsh scripts and sources them, according to your specifications. As such, these scripts are capable of doing some real damage to your system. If you are only downloading scripts from oh-my-zsh and/or prezto, you're probably fine, since there is a second level of manual checking before a script gets into the framework.

But, if you are adding a script from any other source, please check the source code of the plugin to see its not doing anything malicious, before adding it to your .zshrc.