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 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
The best way
$ curl -sL get.zplug.sh | zsh
If you wonder this installation, please check it out:
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 highergit
version 1.7 or higherawk
An AWK variant that's notmawk
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, if:"(( $+commands[git] ))"
zplug "themes/duellj", from:oh-my-zsh
zplug "lib/clipboard", from:oh-my-zsh, if:"[[ $OSTYPE == *darwin* ]]"
# Run a command after a plugin is installed/updated
zplug "tj/n", hook-build:"make install"
# Supports checking out a specific branch/tag/commit
zplug "b4b4r07/enhancd", at:v1
zplug "mollifier/anyframe", at:4c23cb60
# Install if "if:" tag returns true
zplug "hchbaw/opp.zsh", if:"(( ${ZSH_VERSION%%.*} < 5 ))"
# 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, \
hook-build:"chmod 755 *.sh", \
use:"*.sh"
# 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 nice
# 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
zplug "zsh-users/zsh-syntax-highlighting", nice:10
# Can manage local plugins
zplug "~/.zsh", from:local
# A relative path is resolved with respect to the $ZPLUG_HOME
zplug "repos/robbyrussell/oh-my-zsh/custom/plugins/my-plugin", from:local
# 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 |
--version |
Display the version of zplug |
2. Commands for zplug
Command | Description | Options |
---|---|---|
install |
Install packages in parallel | --verbose ,--select |
load |
Source installed plugins and add installed commands to $PATH |
--verbose |
list |
List installed packages (more specifically, view the associative array $zplugs ) |
--select |
update |
Update installed packages in parallel | --self ,--select |
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
If you want to manage zplug by itself, run this command (after installing zplug, of course):
$ zplug update --self
By using the --self
option, zplug will be cloned to $ZPLUG_HOME/repos
and create a symlink to $ZPLUG_HOME/zplug
.
To manage zplug in the same way as any other packages, put the following in your .zshrc
.
zplug "zplug/zplug"
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 (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 ,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 after installation/update | commands (-) | hook-build:"make install" |
hook-load |
Commands to 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 |
nice |
Priority of loading the plugins. If this tag is specified 10 or more, zplug will load plugins after compinit (see also #26) |
-20..19 (0) | nice:19 |
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 (ZPLUG_CLONE_DEPTH ) |
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_HOME/bin
. Because zplug adds $ZPLUG_HOME/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_CLONE_DEPTH
Defaults to 0
. When cloning a Git repository, there is an option to limit the amount of history your clone will have. This environment variable how many commits you want to clone. The value 0
means that zplug will clone the whole history of packages.
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 a cache file to speed up the load process. The cache file is located at $ZPLUG_CACHE_FILE
. If you want to clear the cache, please run zplug clear
or do the following:
$ ZPLUG_USE_CACHE=false zplug load
ZPLUG_CACHE_FILE
Defaults to $ZPLUG_HOME/.cache
. You can change where the cache file is saved, for example, $HOME/.cache/zplug/cache
.
ZPLUG_REPOS
Defaults to $ZPLUG_HOME/repos
. You can change where the repositories are cloned in case you want to manage them separately.
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.