zplug: A Shell repository from washo

Zsh Plugin Manager

Pros.

Can manage everything
- Zsh plugins/UNIX commands on GitHub and Bitbucket
- Gist files (gist.github.com)
- Externally managed plugins e.g., oh-my-zsh and prezto plugins/themes
- Binary artifacts on GitHub Releases
- Local plugins
- etc. (you can add your own sources!)
Super-fast parallel installation/update
Support for lazy-loading
Branch/tag/commit support
Post-update, post-load hooks
Dependencies between packages
Unlike antigen, no ZSH plugin file (*.plugin.zsh) required
Interactive interface (fzf, peco, zaw, and so on)
Cache mechanism for reducing the startup time

DEMO:

Installation

latest	stable

The best way

$ curl -sL --proto-redir -all,https https://raw.githubusercontent.com/zplug/installer/master/installer.zsh | zsh

Curious about the installation script? Check it out at zplug/installer.

Using Homebrew (OS X)

$ brew install zplug

Manually

Cloning from GitHub, and source init.zsh:

$ export ZPLUG_HOME=/path/to/.zplug
$ git clone https://github.com/zplug/zplug $ZPLUG_HOME

Requirements

zsh: version 4.3.9 or higher
git: version 1.7 or higher
awk: An AWK variant that's not mawk

Usage

Add a zplug section to your .zshrc:

List the packages with zplug commands
zplug load to source the plugins and add commands to your $PATH

Example

source ~/.zplug/init.zsh

# Make sure to use double quotes
zplug "zsh-users/zsh-history-substring-search"

# Use the package as a command
# And accept glob patterns (e.g., brace, wildcard, ...)
zplug "Jxck/dotfiles", as:command, use:"bin/{histuniq,color}"

# Can manage everything e.g., other person's zshrc
zplug "tcnksm/docker-alias", use:zshrc

# Disable updates using the "frozen" tag
zplug "k4rthik/git-cal", as:command, frozen:1

# Grab binaries from GitHub Releases
# and rename with the "rename-to:" tag
zplug "junegunn/fzf-bin", \
    from:gh-r, \
    as:command, \
    rename-to:fzf, \
    use:"*darwin*amd64*"

# Supports oh-my-zsh plugins and the like
zplug "plugins/git",   from:oh-my-zsh

# Also prezto
zplug "modules/prompt", from:prezto

# Load if "if" tag returns true
zplug "lib/clipboard", from:oh-my-zsh, if:"[[ $OSTYPE == *darwin* ]]"

# Run a command after a plugin is installed/updated
# Provided, it requires to set the variable like the following:
# ZPLUG_SUDO_PASSWORD="********"
zplug "jhawthorn/fzy", \
    as:command, \
    rename-to:fzy, \
    hook-build:"make && sudo make install"

# Supports checking out a specific branch/tag/commit
zplug "b4b4r07/enhancd", at:v1
zplug "mollifier/anyframe", at:4c23cb60

# Can manage gist file just like other packages
zplug "b4b4r07/79ee61f7c140c63d2786", \
    from:gist, \
    as:command, \
    use:get_last_pane_path.sh

# Support bitbucket
zplug "b4b4r07/hello_bitbucket", \
    from:bitbucket, \
    as:command, \
    use:"*.sh"

# Rename a command with the string captured with `use` tag
zplug "b4b4r07/httpstat", \
    as:command, \
    use:'(*).sh', \
    rename-to:'$1'

# Group dependencies
# Load "emoji-cli" if "jq" is installed in this example
zplug "stedolan/jq", \
    from:gh-r, \
    as:command, \
    rename-to:jq
zplug "b4b4r07/emoji-cli", \
    on:"stedolan/jq"
# Note: To specify the order in which packages should be loaded, use the defer
#       tag described in the next section

# Set the priority when loading
# e.g., zsh-syntax-highlighting must be loaded
# after executing compinit command and sourcing other plugins
# (If the defer tag is given 2 or above, run after compinit command)
zplug "zsh-users/zsh-syntax-highlighting", defer:2

# Can manage local plugins
zplug "~/.zsh", from:local

# Load theme file
zplug 'dracula/zsh', as:theme

# Install plugins if there are plugins that have not been installed
if ! zplug check --verbose; then
    printf "Install? [y/N]: "
    if read -q; then
        echo; zplug install
    fi
fi

# Then, source plugins and add commands to $PATH
zplug load --verbose

Finally, use zplug install to install your plugins and reload .zshrc.

1. Options for `zplug`

Option	Description
`--help`	Display the help message
`--rollback`	Rollback a failed package
`--self-manage`	Self management of zplug
`--version`	Display the version of zplug
`--log`	Show the report of zplug errors

2. Commands for `zplug`

Command	Description	Options
`install`	Install packages in parallel	(None)
`load`	Source installed plugins and add installed commands to `$PATH`	`--verbose`
`list`	List installed packages (more specifically, view the associative array `$zplugs`)	`--select`,`--installed`,`--loaded`
`update`	Update installed packages in parallel	`--select`,`--force`
`check`	Return true if all packages are installed, false otherwise	`--verbose`
`status`	Check if the remote repositories are up to date	`--select`
`clean`	Remove repositories which are no longer managed	`--force`,`--select`
`clear`	Remove the cache file	(None)
`info`	Show the information such as the source URL and tag values for the given package	(None)

Take a closer look

# zplug check returns true if all packages are installed
# Therefore, when it returns false, run zplug install
if ! zplug check; then
    zplug install
fi

# source plugins and add commands to the PATH
zplug load

# zplug check returns true if the given repository exists
if zplug check b4b4r07/enhancd; then
    # setting if enhancd is available
    export ENHANCD_FILTER=fzf-tmux
fi

Let zplug manage zplug

To manage zplug itself like other packages, write the following in your .zshrc.

zplug 'zplug/zplug', hook-build:'zplug --self-manage'

All that's left is to run zplug update.

3. Tags for `zplug`

truthy is any of true, yes, on, 1 and falsy is any of false, no, off, 0.

Tag	Description	Value (default)	Example
`as`	Specify whether to register the package as plugins or commands	`plugin`,`command`,`theme` (`plugin`)	`as:command`
`use`	Specify the pattern of the files to source (for `plugin`) or the relative path to add to the `$PATH` (for `command`) / With `from:gh-r`, zplug tries to guess which file to use from your OS and architecture. You can manually specify `use:"darwin{amd,386}*"` if that doesn't get the right file.	glob (`use:"*.zsh"`)	`use:bin`,`use:".sh"`, `use:darwin*`
`ignore`	Similar to `use` tag, but specify pattern of files you want to ignore (see also #56)	glob (-)	`ignore:"some_*.zsh"`
`from`	Specify where to get the package from	`github`,`bitbucket`, `gh-r`,`gist`, `oh-my-zsh`,`prezto`,`local` (`github`)	`from:gh-r`
`at`	Specify branch/tag/commit to install	revision (`master`)	`at:v1.5.6`
`rename-to`	Specify the filename you want to rename the command to (use this only with `as:command`)	filename (-)	`rename-to:fzf`
`dir`	Installed directory of the package	READ ONLY	`dir:/path/to/user/repo`
`if`	Specify the conditions under which to install and use the package	boolean (-)	`if:"[ -d ~/.zsh ]"`
`hook-build`	Commands to run after installation/update	commands (-)	`hook-build:"make install"`
`hook-load`	Commands to run after loading	commands (-)	`hook-load:"echo 'Loaded!'"`
`frozen`	Do not update unless explicitly specified	truthy,falsy (false)	`frozen:1`
`on`	Load this package only if a different package is installed	package	`on:user/repo`
`defer`	Defers the loading of a package. If the value is 2 or above, zplug will source the plugin after `compinit` (see also #26)	0..3 (0)	`defer:2`
`lazy`	Whether it is an autoload function or not	truthy,falsy (false)	`lazy:true`
`depth`	The number of commits to include in the cloned repository. 0 means the whole history.	Any non-negative integer	`depth:10`

Changing the defaults

You can use zstyle to change the default value. The format is:

zstyle ":zplug:tag" tag_name new_default_value

For example, if you have a lot of commands and not so many plugins, (i.e. if you find yourself specifying as:command often), you can do:

zstyle ":zplug:tag" as command

The default value for all tags can be changed in this way.

Available on CLI

You can register packages to zplug from the command-line. If you use zplug from the command-line, it is possible to add stuff more easily with the help of powerful zsh completions.

In this case, zplug spit out its settings to $ZPLUG_LOADFILE instead of .zshrc. If you launch new zsh process, zplug load command automatically search this file and run source command.

See ZPLUG_LOADFILE for other usage of ZPLUG_LOADFILE.

4. Environment variables for `zplug`

`ZPLUG_HOME`

Defaults to ~/.zplug. zplug will store/load packages in this directory. The directory structure is shown below.

$ZPLUG_HOME
|-- bin
|   `-- some_command -> ../repos/username_A/reponame1/some_command
`-- repos
    |-- username_A
    |   |-- reponame1
    |   |   |-- README.md
    |   |   `-- some_command
    |   `-- reponame2
    |       |-- README.md
    |       `-- some_plugin.zsh
    `-- username_B
        `-- reponame1

If you specify as:command, zplug will see the package as a command and create a symbolic link of the same name (if you want to rename it, use the rename-to: tag) in $ZPLUG_BIN. Because zplug adds $ZPLUG_BIN to the $PATH, you can run that command from anywhere.

`ZPLUG_THREADS`

The number of threads zplug uses when installing/updating. The default value is 16.

`ZPLUG_PROTOCOL`

Defaults to HTTPS. Valid options are HTTPS and SSH. Unless you have a specific reason, you should use the HTTPS protocol.

For more information, see also Which remote URL should I use? - GitHub Help

`ZPLUG_FILTER`

Defaults to fzf-tmux:fzf:peco:percol:zaw. When --select option is specified, the first element in the colon-separated list that exists in the $PATH will be used by zplug as the interactive filter. You can also use spaces and double quotes in ZPLUG_FILTER like: fzf-tmux -d "10%":/path/to/peco:my peco.

`ZPLUG_LOADFILE`

Defaults to $ZPLUG_HOME/packages.zsh. This file is used to add plugins from zplug on the command-line. It is also a useful place to isolate your packages list from .zshrc. Rather than cluttering your .zshrc with many lines enumerating packages, you can put them in a separate file and set ZPLUG_LOADFILE to its path.

`ZPLUG_USE_CACHE`

Defaults to true. If this variable is true, zplug will use cache files to speed up the load process. The cache files are saved under the $ZPLUG_CACHE_DIR directory. If you want to clear the cache, please run zplug clear or do the following:

$ ZPLUG_USE_CACHE=false zplug load

`ZPLUG_CACHE_DIR`

Defaults to $ZPLUG_HOME/.cache. You can change where the cache file is saved, for example, ~/.cache/zplug.

`ZPLUG_REPOS`

Defaults to $ZPLUG_HOME/repos. You can change where the repositories are cloned in case you want to manage them separately.

`ZPLUG_SUDO_PASSWORD`

Defaults to ''. You can set sudo password for zplug's hook-build tag. However, this variable should not be managed in dotfiles and so on.

`ZPLUG_LOG_LOAD_SUCCESS`

Defaults to false. If true, zplug spit the log about its success operation out to file (you can see it with zplug --log).

`ZPLUG_LOG_LOAD_FAILURE`

Defaults to false. If true, zplug spit the log about its failure operation out to file (you can see it with zplug --log).

# your .zshrc
source ~/.zshrc_secret
zplug "some/command", hook-build:"make && sudo make install"

`ZPLUG_BIN`

Defaults to $ZPLUG_HOME/bin. You can change the save destination of the command's symbolic link, e.g. ~/bin.

External commands

zplug, like git(1), supports external commands. These are executable scripts that reside somewhere in the PATH, named zplug-cmdname, which can be invoked with zplug cmdname. This allows you to create your own commands without modifying zplug's internals. Instructions for creating your own commands can be found in the docs. Check out the sample zplug-env external command for an example.

V.S.

zplug is the fastest among the famous zsh plugin managers. Numbers? Here they are:

Note

Not antigen 💉 but zplug 🌺 will be here for you from now on.
🌺 It was heavily inspired by vim-plug, neobundle.vim and the like.

Other resources

awesome-zsh-plugins is a list of ZSH plugins, themes and completions that you can use with zplug.

For migration from antigen, zgen, or zplug v1, check out the wiki page.

License

MIT (c) @b4b4r07

washo/zplug

Pros.

Installation

The best way

Using Homebrew (OS X)

Manually

Requirements

Usage

Example

1. Options for zplug

2. Commands for zplug

Take a closer look

Let zplug manage zplug

3. Tags for zplug

Changing the defaults

Available on CLI

4. Environment variables for zplug

ZPLUG_HOME

ZPLUG_THREADS

ZPLUG_PROTOCOL

ZPLUG_FILTER

ZPLUG_LOADFILE

ZPLUG_USE_CACHE

ZPLUG_CACHE_DIR

ZPLUG_REPOS

ZPLUG_SUDO_PASSWORD

ZPLUG_LOG_LOAD_SUCCESS

ZPLUG_LOG_LOAD_FAILURE

ZPLUG_BIN