🇺🇸 🇯🇵
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 zplug.sh/installer | zsh
If you wonder this installation, please check it out:
Homebrew (OS X)
Using$ 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 quoteszplug "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 zshrczplug "tcnksm/docker-alias", use:zshrc # Disable updates using the "frozen" tagzplug "k4rthik/git-cal", as:command, frozen:1 # Grab binaries from GitHub Releases# and rename with the "rename-to:" tagzplug "junegunn/fzf-bin", \ from:gh-r, \ as:command, \ rename-to:fzf, \ use:"*darwin*amd64*" # Supports oh-my-zsh plugins and the likezplug "plugins/git", from:oh-my-zsh # Also preztozplug "modules/prompt", from:prezto # Load if "if" tag returns truezplug "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 } &>/dev/null " # Supports checking out a specific branch/tag/commitzplug "b4b4r07/enhancd", at:v1zplug "mollifier/anyframe", at:4c23cb60 # Can manage gist file just like other packageszplug "b4b4r07/79ee61f7c140c63d2786", \ from:gist, \ as:command, \ use:get_last_pane_path.sh # Support bitbucketzplug "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 examplezplug "stedolan/jq", \ from:gh-r, \ as:command, \ rename-to:jqzplug "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 cominit command)zplug "zsh-users/zsh-syntax-highlighting", defer:2 # Can manage local pluginszplug "~/.zsh", from:local # Load theme filezplug 'dracula/zsh', as:theme # Install plugins if there are plugins that have not been installedif ! zplug check --verbose; then printf "Install? [y/N]: " if read -q; then echo; zplug install fifi # Then, source plugins and add commands to $PATHzplug load --verbose
Finally, use zplug install
to install your plugins and reload .zshrc
.
zplug
1. Options for Option | Description |
---|---|
--help |
Display the help message |
--version |
Display the version of zplug |
--log |
Show the error log (for developer) |
zplug
2. Commands for 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 |
update |
Update installed packages in parallel | --self ,--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 installif ! zplug check; then zplug installfi # source plugins and add commands to the PATHzplug load # zplug check returns true if the given repository existsif zplug check b4b4r07/enhancd; then # setting if enhancd is available export ENHANCD_FILTER=fzf-tmuxfi
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
so that zplug can be managed by itself.
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
.
zplug
3. Tags for 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 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 |
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
.
zplug
4. Environment variables for 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_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 shoud not be managed in dotfiles and so on.
# your .zshrcsource ~/.zshrc_secretzplug "some/command", hook-build:"make && sudo make install"
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.