zplug: A Shell repository from dojineko

Zsh Plugin Manager

Pros.

Can manage everything
- Zsh plugins/UNIX commands on GitHub and Bitbucket
- Gist file (gist.github.com)
- Externally managed plugins e.g., oh-my-zsh plugins/themes
- Birary artifacts on GitHub Releases
- etc.
Super-fast parallel installation/update
Branch/tag/commit support
Post-update hooks
Dependencies between plugins
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

Download zplug and put it in ~/.zplug

$ curl -fLo ~/.zplug/zplug --create-dirs https://git.io/zplug

Usage

Add a zplug section to your .zshrc:

List the plugins/commands with zplug commands
zplug load to source the plugins and add its commands to your $PATH

Example

source ~/.zplug/zplug

# Make sure you use double quotes
zplug "zsh-users/zsh-history-substring-search"

# Can manage a plugin as a command
# And accept glob patterns (e.g., brace, wildcard, ...)
zplug "Jxck/dotfiles", as:command, of:"bin/{histuniq,color}"

# Can manage everything e.g., other person's zshrc
zplug "tcnksm/docker-alias", of:zshrc

# Prohibit updates to a plugin by using the "frozen:" tag
zplug "k4rthik/git-cal", as:command, frozen:1

# Grab binaries from GitHub Releases
# and rename to use "file:" tag
zplug "junegunn/fzf-bin", \
    as:command, \
    from:gh-r, \
    file:fzf, \
    of:"*darwin*amd64*"

# Support oh-my-zsh plugins and the like
zplug "plugins/git",   from:oh-my-zsh, if:"which 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", do:"make install"

# Support checking out a specific branch/tag/commit of a plugin
zplug "b4b4r07/enhancd", at:v1
zplug "mollifier/anyframe", commit:4c23cb60

# Install if "if:" tag returns true
zplug "hchbaw/opp.zsh", if:"(( ${ZSH_VERSION%%.*} < 5 ))"

# Can manage gist file just like other plugins
zplug "b4b4r07/79ee61f7c140c63d2786", \
    from:gist, \
    as:command, \
    of:get_last_pane_path.sh

# Support bitbucket
zplug "b4b4r07/hello_bitbucket", \
    as:command
    from:bitbucket, \
    do:"chmod 755 *.sh", \
    of:"*.sh"

# Group dependencies, emoji-cli depends on jq in this example
zplug "stedolan/jq", \
    as:command, \
    file:jq, \
    from:gh-r \
    | zplug "b4b4r07/emoji-cli"

# Set priority to load command like a nice command
# e.g., zsh-syntax-highlighting must be loaded
# after executing compinit command and sourcing other plugins
zplug "zsh-users/zsh-syntax-highlighting", nice:10

# 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. `zplug` commands

Command	Description	Option
`install`	Install described items (plugins/commands) in parallel	`--verbose`,`--select`
`load`	Source installed plugins and add installed commands to `$PATH`	`--verbose`
`list`	List installed items (Strictly speaking, view the associative array `$zplugs`)	`--select`
`update`	Update installed items in parallel	`--self`,`--select`
`check`	Return false if there are not installed items	`--verbose`,`--select`
`status`	Check if the remote repositories are up to date	`--select`
`clean`	Remove repositories which are no longer managed	`--force`,`--select`
`cache`	Remove the cache file	`--force`

Take a closer look

# zplug check return true if all plugins are installed
# Therefore, when it returns not true (thus false),
# run zplug install
if ! zplug check; then
    zplug install
fi

# source and add to the PATH
zplug load

# zplug check returns true if argument 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 --self option, zplug will be cloned to $ZPLUG_HOME/repos and be created symlink to $ZPLUG_HOME/zplug.

Then to start to manage zplug in the same way as any other plugins, please write the following in your .zshrc.

zplug "b4b4r07/zplug"

All that's left is to run zplug update.

2. `zplug` tags

Tag	Description	Value (default)	Example
`as`	Specify whether to register as commands or to register as plugins	`plugin`,`command` (`plugin`)	`as:command`
`of`	Specify the pattern to source files (for `plugin`) or specify relative path to add to the `$PATH` (for `command`) / In case of `from:gh-r`, can specify `of:"darwin{amd,386}*"` and so on	- (`of:"*.zsh"`)	`of:bin`,`of:".sh"`, `of:darwin*`
`from`	Specify the services you use to install	`github`,`bitbucket`, `gh-r`,`gist`, `oh-my-zsh` (`github`)	`from:gh-r`
`at`	Support branch/tag installation	branch/tag name (`master`)	`at:v1.5.6`
`file`	Specify filename you want to rename (only `as:plugin`)	filename (-)	`file:fzf`
`dir`	Installation directory which is managed by zplug	READ ONLY	`dir:/path/to/user/repo`
`if`	Specify the conditions under which to run `source` or add to `$PATH`	true or false (-)	`if:"[ -d ~/.zsh ]"`
`do`	Run commands after installation/update	commands (-)	`do:make install`
`frozen`	Do not update unless explicitly specified	0,1 (0)	`frozen:1`
`commit`	Support commit installation (regardless of whether the `$ZPLUG_SHALLOW` is true or not)	commit hash (-)	`commit:4428d48`
`on`	Dependencies	READ ONLY	`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`

Available on CLI

You can register plugins or commands to zplug on the command-line. If you use zplug on the command-line, it is possible to write more easily its settings by grace of the command-line completion.

In this case, zplug spit out its settings to $ZPLUG_EXTERNAL instead of .zshrc. If you launch new zsh process, zplug load command automatically search this file and run source command.

3. `zplug` configurations

`ZPLUG_HOME`

Defaults to ~/.zplug. zplug will store/load plugins in this directory. The directory structure is 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 in zplug command, zplug will recognize the plugin as a command and create a symbolic link of the same name (if you want to rename it, set file: tag) within $ZPLUG_HOME/bin. Because zplug adds $ZPLUG_HOME/bin to the $PATH, you can run that command from any directories.

`ZPLUG_THREADS`

The number of threads zplug should use. The default value is 16.

`ZPLUG_PROTOCOL`

Defaults to HTTPS. Valid options for $ZPLUG_PROTOCOL are HTTPS or 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_SHALLOW`

Defaults to true. When cloning a Git repository, there is an option to limit the amount of history your clone will have. If you set this environment variable to true, you get the least amount of history, and you create a shallow clone.

`ZPLUG_FILTER`

Defaults to fzf-tmux:fzf:peco:percol:zaw. When --select option is specified, colon-separated first element that exists in the $PATH will be used by zplug as the interactive filter. The ZPLUG_FILTER also accepts the following values: fzf-tmux -d "10%":/path/to/peco:my peco.

`ZPLUG_EXTERNAL`

Defaults to $ZPLUG_HOME/init.zsh. This file is used to add plugins from zplug on the command-line.

`ZPLUG_USE_CACHE`

Defaults to true. If this variable is set, zplug comes to use a cache to speed up when it will load plugins after the first. The cache file is located in $ZPLUG_HOME/.cache. If you want to clear the cache, please run zplug clear or do the following:

$ ZPLUG_USE_CACHE=false zplug load

V.S.

zplug is the fastest of famous plugin managers for zsh. The figures are graphs showing the facts.

Note

🎉 Congrats! Released v1.0.0 version!!
~~🚧 Until version 1.0.0 is released, zplug may be changed in ways that are not backward compatible.~~
🎨 Design vision
- Fantabulous plugin
- Without simple, but without complex
- Manage everything
Not antigen 💉 but zplug 🌺 will be here to stay 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.

dojineko/zplug

Pros.

Installation

Usage

Example

1. `zplug` commands

Take a closer look

Let zplug manage zplug

2. `zplug` tags

Available on CLI

3. `zplug` configurations

`ZPLUG_HOME`

`ZPLUG_THREADS`

`ZPLUG_PROTOCOL`

`ZPLUG_SHALLOW`

`ZPLUG_FILTER`

`ZPLUG_EXTERNAL`

`ZPLUG_USE_CACHE`

V.S.

Note

Other resources

License

dojineko/zplug

Pros.

Installation

Usage

Example

1. zplug commands

Take a closer look

Let zplug manage zplug

2. zplug tags

Available on CLI

3. zplug configurations

ZPLUG_HOME

ZPLUG_THREADS

ZPLUG_PROTOCOL

ZPLUG_SHALLOW

ZPLUG_FILTER

ZPLUG_EXTERNAL

ZPLUG_USE_CACHE

V.S.

Note

Other resources

License

1. `zplug` commands

2. `zplug` tags

3. `zplug` configurations

`ZPLUG_HOME`

`ZPLUG_THREADS`

`ZPLUG_PROTOCOL`

`ZPLUG_SHALLOW`

`ZPLUG_FILTER`

`ZPLUG_EXTERNAL`

`ZPLUG_USE_CACHE`