Skip to content

Configurations

Jump to bottom
Naoki Mizuno edited this page Dec 20, 2015 · 7 revisions

This page describes how to manage plugins with zplug. We will go over the available tags and some features such as expressing dependencies, and provide you with a sample .zshrc to get you started with your customization.

Basic usage

The very basic format for telling zplug to manage a plugin is:

zplug "USERNAME/REPONAME"

This needs to go after sourcing zplug and before calling zplug load. The following example shows this in action, as well as a useful mechanism to download zplug automatically if it's not installed.

Examples

# Check if zplug is installed
[[ -d ~/.zplug ]] || {
  curl -fLo ~/.zplug/zplug --create-dirs https://git.io/zplug
  source ~/.zplug/zplug && zplug update --self
}

# Essential
source ~/.zplug/zplug

# Make sure to use double quotes to prevent shell expansion
zplug "zsh-users/zsh-syntax-highlighting"

# Add a bunch more of your favorite plugins!

# Install plugins that have not been installed yet
if ! zplug check --verbose; then
    printf "Install? [y/N]: "
    if read -q; then
        echo; zplug install
    else
        echo
    fi
fi

zplug load

Tags

You can use tags to customize the behavior of zplug. Here is a list of available tags.

as tag

Possible values: plugin, command

Default value: plugin

plugin

zplug will source *.zsh or *.plugin.zsh files in the root of the project directory by default, unless a pattern is specified with the of tag.

Examples
zplug "mollifier/zload", as:plugin
# Same as:
zplug "mollifier/zload"

command

zplug will see the plugin as a command and adds it to $PATH.

Examples
  • k4rthik/git-cal
    • lets you see a GitHub contribution-like calendar with the git-cal command.
zplug "k4rthik/git-cal", as:command

of tag

Default value: "*.zsh"

Use this tag if the file(s) you want to source do not match the default pattern or if there are directories that you want to add to your $PATH.

Examples

# Source a file that isn't a .zsh file
zplug "rupa/z", of:z.sh
# Specify relative directory to add to $PATH
zplug "rcmdnk/sentaku", as:command, of:bin
# Source someone else's zshrc
zplug "tcnksm/docker-alias", of:zshrc
# Use someone else's commands
zplug "Jxck/dotfiles", as:command, of:"bin/{histuniq,color}"

from tag

Specify where to get the plugin from.

Possible values: github, bitbucket, oh-my-zsh, gh-r, gist, local

Default value: github

  • github
    • the repo is hosted on GitHub.
  • bitbucket
    • the repo is hosted on Bitbucket.
  • oh-my-zsh
    • plugin is included in Oh My Zsh.
  • gh-r
    • grab binaries from GitHub Releases.
  • gist
    • the file is on GitHub Gist.
  • local
    • have zplug manage files on your local file system

Examples

# from:gh-r
zplug "peco/peco",          as:command, from:gh-r
zplug "monochromegane/hoi", as:command, from:gh-r, of:"darwin_amd64"
# from:oh-my-zsh
# Note: see also the "nice" tag section when using completions from Oh My Zsh
zplug "plugins/git",  from:oh-my-zsh, as:plugin
zplug "plugins/brew", from:oh-my-zsh
# from:gist
zplug "b4b4r07/79ee61f7c140c63d2786", from:gist, as:command, of:"*.sh"
# from:local
zplug "~/.local_zshrc", from:local

at and commit tags

Specify the branch/tag or the commit that you want to use.

Examples

# Note: commacd is only available for bash, but shown for the sake of demo
zplug "shyiko/commacd",     at:develop
zplug "mollifier/anyframe", commit:4c23cb60
zplug "petdance/ack2",      as:command, at:2.14

if tag

Source or add to $PATH only if the conditions are met.

Examples

# Use lib/clipboard plugin only on Mac
zplug "lib/clipboard", from:oh-my-zsh, if:"[[ $OSTYPE == *darwin* ]]"

file tag

Use this tag if you have a specific name that you want to install the plugin as.

Examples

# Install if jq command is not installed and rename JSON.sh to jq
zplug "dominictarr/JSON.sh", if:"! which jq", file:jq
# Install if jq is available
zplug "b4b4r07/emoji-cli",   if:"which jq"

do tag

Specify commands to run after installation or update.

Examples

  • tj/n
    • Node version management
# Install the n command
zplug "tj/n", do:"PREFIX=$ZPLUG_HOME make install"
# But this is probably better since zplug can remove it when uninstalling
zplug "tj/n", as:command, of:bin/n
# Make all .sh files executable and add them to $PATH
zplug "b4b4r07/hello_bitbucket", \
    as:command, \
    from:bitbucket, \
    do:"chmod 755 *.sh", \
    of:"*.sh"

frozen tag

Default value: 0

Don't update unless explicitly specified.

Examples

zplug "b4b4r07/enhancd", frozen:1, at:v1

nice tag

Possible values: an integer in range [-20, 19] (inclusive)

Default value: 0

Set the priority of the plugin. Plugins with higher niceness are loaded after plugins with lower niceness. Niceness of 10 or higher results in plugins being loaded after compinit is called.

Examples

  • knu/z
    • A fork of rupa/z with much improved zsh/bash completion and better results
# Source after compinit to enable completion
zplug "knu/z", of:z.sh, nice:10

ignore tag

Specify file(s) to ignore, relative to the project root. For oh-my-zsh plugins (i.e. when using from:oh-my-zsh), the project root is $ZPLUG_HOME/repos/robbyrussell/oh-my-zsh

There is no need to specify the ignore tag if the plugin directory you want to load doesn't have any *.zsh files (for example, only has files that start with an underscore like _foo for completion).

Examples

# plugins/golang is a completion plugin written in a .zsh file. There is no
# need to source oh-my-zsh.sh in the project root directory, which overrides
# environment variables and adds functions (see issue #56 for details).
zplug "plugins/golang", from:oh-my-zsh, ignore:oh-my-zsh.sh, nice:10
# There are no .zsh files in plugins/adb so no need to specify nice or ignore
zplug "plugins/adb", from:oh-my-zsh

Dependencies

You can specify the order in which plugins are installed and loaded.

Use pipes | to express dependencies.

zplug "b4b4r07/emoji-cli", if:"which jq"
# This can be rewritten as the following
zplug "stedolan/jq", \
    as:command, \
    file:jq, \
    from:gh-r \
    | zplug "b4b4r07/emoji-cli"

Sample .zshrc

This is an example .zshrc for zplug that demonstrates the use of various tags.

# Check if zplug is installed
[[ -d ~/.zplug ]] || {
  curl -fLo ~/.zplug/zplug --create-dirs https://git.io/zplug
  source ~/.zplug/zplug && zplug update --self
}

# Essential
source ~/.zplug/zplug

# What does this do?
zplug "junegunn/fzf-bin", \
    from:gh-r, \
	at:0.11.0, \
    as:command, \
    of:"*darwin*amd64*", \
    file:fzf
# It grabs the binary of fzf-bin version 0.11.0 from GitHub Release and uses
# the file that matches "*darwin*amd64" as a command called fzf!

# Then, source plugins and add commands to $PATH
zplug load --verbose

Other people's settings

Clone this wiki locally