Home

Awesome

:us: :jp:

Zsh Plugin Manager

Travis Latest Slack

<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>

Pros.

DEMO:

<!-- [![](https://raw.githubusercontent.com/b4b4r07/screenshots/master/zplug/install.gif)][repo] -->

Installation

lateststable
LatestStable

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

Usage

Add a zplug section to your .zshrc:

  1. List the packages with zplug commands
  2. 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

OptionDescription
--helpDisplay the help message
--rollbackRollback a failed package
--self-manageSelf management of zplug
--versionDisplay the version of zplug
--logShow the report of zplug errors

2. Commands for zplug

CommandDescriptionOptions
installInstall packages in parallel(None)
loadSource installed plugins and add installed commands to $PATH--verbose
listList installed packages (more specifically, view the associative array $zplugs)--select,--installed,--loaded
updateUpdate installed packages in parallel--select,--force
checkReturn true if all packages are installed, false otherwise--verbose
statusCheck if the remote repositories are up to date--select
cleanRemove repositories which are no longer managed--force,--select
clearRemove the cache file(None)
infoShow 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.

<!-- [![](https://raw.githubusercontent.com/b4b4r07/screenshots/master/zplug/update.gif)][repo] -->

3. Tags for zplug

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

TagDescriptionValue (default)Example
asSpecify whether to register the package as plugins or commandsplugin,command,theme (plugin)as:command
useSpecify 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*
ignoreSimilar to use tag, but specify pattern of files you want to ignore (see also #56)glob (-)ignore:"some_*.zsh"
fromSpecify where to get the package fromgithub,bitbucket,<br>gh-r,gist,<br>oh-my-zsh,prezto,local (github)from:gh-r
atSpecify branch/tag/commit to installrevision (master)at:v1.5.6
rename-toSpecify the filename you want to rename the command to (use this only with as:command)filename (-)rename-to:fzf
dirInstalled directory of the packageREAD ONLYdir:/path/to/user/repo
ifSpecify the conditions under which to install and use the packageboolean (-)if:"[ -d ~/.zsh ]"
hook-buildCommands to run after installation/updatecommands (-)hook-build:"make install"
hook-loadCommands to run after loadingcommands (-)hook-load:"echo 'Loaded!'"
frozenDo not update unless explicitly specifiedtruthy,falsy (false)frozen:1
onLoad this package only if a different package is installedpackageon:user/repo
deferDefers 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
lazyWhether it is an autoload function or nottruthy,falsy (false)lazy:true
depthThe number of commits to include in the cloned repository. 0 means the whole history.Any non-negative integerdepth: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

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