Awesome
:us: :jp:
<div align="center"> <a href="http://zplug.sh"> <img width=650px src="https://raw.githubusercontent.com/b4b4r07/screenshots/master/zplug/logo.png"> </a> </div> <br>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:
<!-- [![](https://raw.githubusercontent.com/b4b4r07/screenshots/master/zplug/install.gif)][repo] -->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 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", \
from:gh-r, \
as:command, \
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 ,<br>gh-r ,gist ,<br>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.
<!-- [![](https://raw.githubusercontent.com/b4b4r07/screenshots/master/zplug/cli.gif)][repo] -->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 :syringe: but zplug :hibiscus: will be here for you from now on.
- :hibiscus: 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.