= antidote-bundle(1)
:doctype: manpage
:manmanual: Antidote Manual
:mansource: antidote

== Name
antidote-bundle - download a bundle and print its source line

== Synopsis
*antidote bundle* [<bundles>...]

== Description
*antidote-bundle* assembles your Zsh plugins. Bundles can be git repos, or local files or directories. If a plugin is a repo, it will be cloned if necessary. The zsh code necessary to load (source) the plugin is then printed.

----
antidote bundle gituser/gitrepo
antidote bundle $ZSH_CUSTOM/plugins/myplugin
antidote bundle ${ZDOTDIR:-$HOME}/.zlibs/myfile.zsh
----

Bundles also support annotations. Annotations allow you have finer grained control over your plugins. Annotations are used in the form `keyword:value`.

`kind`::
  * *zsh*: A zsh plugin. This is the default kind of bundle.
  * *fpath*: Only add the plugin to your `$fpath`.
  * *path*: Add the plugin to your `$PATH`.
  * *clone*: Only clone a plugin, but don't do anything else with it.
  * *defer*: Defers loading of a plugin using `romkatv/zsh-defer`.
  * *autoload*: Autoload all the files in the plugin directory as zsh functions.
`branch`::
  The branch annotation allows you to change the default branch of a plugin's repo from *main* to a branch of your choosing.
`path`::
  The path annotation allows you to use a subdirectory or file within a plugin's structure instead of the root plugin (eg: `path:plugins/subplugin`).
`conditional`::
  The conditional annotation allows you to wrap an *if* statement around a plugin's load script. Supply the name of a zero argument zsh function to conditional to perform the test (eg: `conditional:is-macos`).
`pre` / `post`::
  The pre and post annotations allow you to call a function before or after a plugin's load script. This is helpful when configuring plugins, since the configuration functions will only run for active plugins. Supply the name of a zero argument zsh function to pre or post.
`autoload`::
  The autoload annotation allows you to autoload a zsh functions directory in addition to however the plugin was loaded as specified by `kind`. Supply a relative path to autoload (eg: `autoload:functions`).
`pin`::
  The pin annotation allows you to lock a bundle to a specific commit SHA (eg: `pin:abc1234`). A pinned bundle will be cloned at the specified commit and will be skipped during `antidote update`. This is useful for preventing unwanted upstream changes from affecting your environment. Use `branch:` for tags or branches.

Cloned repo directory naming can be controlled with the following `zstyle`:

----
zstyle ':antidote:bundle' path-style full     # github.com/owner/repo (default)
zstyle ':antidote:bundle' path-style short    # owner/repo
zstyle ':antidote:bundle' path-style escaped  # https-COLON--SLASH--SLASH-github.com-SLASH-owner-SLASH-repo
----

== Options
*-h, --help*:: Show the help documentation.
*<bundles>...*:: Zsh plugin bundles.

== Examples

Using the *kind:* annotation:

----
# a regular plugin (kind:zsh is implied, so it's unnecessary)
antidote bundle zsh-users/zsh-history-substring-search kind:zsh
----

----
# add prompt plugins to $fpath
antidote bundle sindresorhus/pure kind:fpath
----

----
# add utility plugins to $PATH
antidote bundle romkatv/zsh-bench kind:path
----

----
# clone a repo for use in other ways
antidote bundle mbadolato/iTerm2-Color-Schemes kind:clone
----

----
# autoload a functions directory
antidote bundle sorin-ionescu/prezto path:modules/utility/functions kind:autoload
----

----
# defer a plugin to speed up load times
antidote bundle olets/zsh-abbr kind:defer
----

Using the *branch:* annotation:

----
# don't use the main branch, use develop instead
antidote bundle zsh-users/zsh-autosuggestions branch:develop
----

Using the *path:* annotation:

----
# load oh-my-zsh
antidote bundle ohmyzsh/ohmyzsh path:lib
antidote bundle ohmyzsh/ohmyzsh path:plugins/git
----

Using the *pin:* annotation:

----
# pin a plugin to a specific commit SHA
antidote bundle zsh-users/zsh-autosuggestions pin:abc1234
----

----
# pin a plugin to a specific commit SHA
antidote bundle zsh-users/zsh-syntax-highlighting pin:abc1234
----

Using the *conditional:* annotation:

----
# define a conditional function prior to loading antidote
function is_macos {
  [[ $OSTYPE == darwin* ]] || return 1
}

# conditionally load a plugin using the function you made
antidote bundle ohmyzsh/ohmyzsh path:plugins/macos conditional:is_macos
----
