zplug

by zplug

zplug / zplug

:hibiscus: A next-generation plugin manager for zsh

4.3K Stars 183 Forks Last release: almost 3 years ago (2.4.2) MIT License 918 Commits 15 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

:us: :jp:

Zsh Plugin Manager

Travis Latest Slack


Pros.

  • Can manage everything
  • 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
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
:
  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-bin",
from:gh-r,
as:command,
rename-to:fzf,
use:"darwinamd64*"

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

License

MIT (c) @b4b4r07

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.