ZPM - Zsh Plugin Manager

Fastest, configurable and extensible zsh plugin manager

Zpm is a plugin manager for ZSH who combines the imperative and declarative approach. At first run, zpm will do complex logic and generate cache, after that will be used cache only, so it makes this framework to be very fast.

Features

• Speed. Fastest plugin manager (Really, after the first run, zpm will not be used at all)
• Compatibility. Zpm plugins are compatible with oh-my-zsh
• Portability. Zpm runs on Linux, Android, OpenWrt, FreeBSD and macOS
• Support for async loading
• Dependencies between packages
• Hooks
• Function autoloading
• Extensible
• Possibility to use github/gitlab/bitbucket mirrors (useful for China)

Table of Contents

• Features
• Table of Contents
• Stats
• Base dependences
• Installation
• How to use
  • Load plugin
  • Plugin name
  • Plugin tags
  • if and if-not conditions
  • Upgrade
  • Clean
• Configuration
• Troubleshooting
• Developing process
• TODO
• Changelog

Stats

Base dependences

• zsh
• git
• One of these:
  • GNU Parallel for fastest parallel execution.
  • Rush for fastest parallel execution.
  • xargs as fallback
• curl for GitHub Gists
• Termux for Android
• cli-html view html in terminal. Optional
• cli-markdown view markdown in terminal. Optional

Installation

Add the following text into .zshrc

if [[ ! -f ~/.zpm/zpm.zsh ]]; then
  git clone --recursive https://github.com/zpm-zsh/zpm ~/.zpm
fi
source ~/.zpm/zpm.zsh

If you don't have .zshrc copy example of .zshrc from zpm

ln -sf ~/.zpm/zshrc ~/.zshrc

How to use

Currently zpm has following commands

• load - will download and load plugin See
• if/if-not - conditions for following command See
• upgrade - will upgrade plugin, without parameters will upgrade all plugins See
• clean - will clean zpm cache See

The set of commands can be expanded extended using plugins

Load plugin

Important

Be carefully, zpm doesn't guarantee loading order in call. So if you need to load a plugin before antoher, you should do 2 separate zpm load calls. This is very important for oh-my-zsh plugins, because @omz-core should be loaded before

Plugin name must have next form: @plugin-type/user/plugin-name. This plugin can be enabled using

# Add to `~/.zshrc` after zpm initialization:
zpm load @plugin-type/user/plugin-name

Notice: if you change ~/.zshrc, you need to remove zpm cache using: zpm clean

Additionaly they can have some tags. Tags must be separated by commas , without spaces, tag parameters must be separated from tag names or another tag parameters by :

# plugin type
#    |   plugin name
#    |      |     tag
#    |      |      |  tag parameters,
#    |      |      |  divided by `:`    boolean tag
#    |      |      |         |              |
#    ↓      ↓      ↓         ↓              ↓
@type/some/plugin,apply:source:path:fpath,async

Plugin name

If plugin name starts with @word, this word will be used as plugin type. Plugin name will be used to detect plugin origin url.

• @github/ or @gh/ - plugin will be cloned from GitHub, this is default value, so you don't need to set it

• @gitlab/ or @gl/ - plugin will be cloned from GitLab

• @bitbucket/ or @bb/ - plugin will be cloned from Bitbucket

• @git/ - plugin will be cloned via git. Be careful, zpm can't detect origin for this plugin type, you must specify origin using tag origin:

• @gist/ - plugin will be downloaded from GitHub Gist

• @omz/ - zpm will use a plugin from oh-my-zsh, oh-my-zsh will be download if not installed. Important: you shoud load @omz before any other plugin from on-my-zsh: zpm load @omz.

  • @omz/theme/ - will load a theme from omz dir: <omz-dir>/themes/*.zsh-theme
  • @omz/lib/ - will load a lib from omz dir: <omz-dir>/lib/*.zsh
  • Example:

  See: https://github.com/zpm-zsh/zpm/issues/24

  # Pull in OMZ (doesn't actually source anything)
  zpm load @omz
  
  # Load any OMZ libraries we want or our OMZ plugins require
  zpm load                \
    @omz/lib/compfix      \
    @omz/lib/completion   \
    @omz/lib/directories  \
    @omz/lib/functions    \
    @omz/lib/git          \
    @omz/lib/grep         \
    @omz/lib/history      \
    @omz/lib/key-bindings \
    @omz/lib/misc         \
    @omz/lib/spectrum     \
    @omz/lib/theme-and-appearance
  
    # Load some OMZ plugins and theme
    zpm load          \
      @omz/virtualenv \
      @omz/git
  
    zpm load @omz/theme/robbyrussell

• @dir - special type, zpm will create a symlink to local directory from origin tag

• @file - special type, zpm will create a symlink to file from origin tag. Should be used for plugins that are written in single file, without additional dependencies

• @remote/ - plugin will be downloaded using curl, for example from an HTTP site. Be careful, zpm can't detect origin for this plugin type, you must specify origin using tag origin:

• @exec/ - special type, zpm will create plugin, completion or binary via executing of origin tag content. See destination tag

• @empty/ - special type, zpm will create empty dir without files. Useful with hook tag.

plugin-from/github  # @github doesn't necessary
@gitlab/plugin-from/gitlab
@bitbucket/plugin-from/bitbucket
@omz/some-plugin
@empty/custom/empty-plugin
@empty/another-empty-plugin

Plugin tags

apply tag

This tag has 3 possible arguments divided by :

• source - load zsh plugin file, enabled by default. File name can be changed using source tag
• path - add directory to your $PATH, by default - /bin dir, enabled by default. Directory name can be changed using path tag
• fpath - add directory to your $fpath, by default or /functions dir if it exists, or plugin root dir if exist at least one _* file, enabled by default. Directory name can be changed using fpath tag

zpm load some/plugin,apply:source:path:fpath
zpm load another/plugin,apply:path # zpm will only add /bin dir to $PATH, plugin will not be sourced, nor be added to $fpath

async tag

If this tag is present, zsh plugin will be loaded async

source tag

Define own file that will be loaded

zpm some/plugin,source:/other.file.zsh

path and fpath tags

Using these tags you can change the destination of folders which will be added to $PATH or $fpath

zpm some/plugin,path:/executables
zpm another/plugin,fpath:/completions

autoload tag

This tag defines functions that will be autoloaded by zpm (using autoload -Uz) divided by :

zpm load some/plugin,autoload:one:two:three

origin tag

All plugins have internal origin type property, like: git, dir, file, remote. You can define own origin, but you can't mix different types of origin types. So, you can define Gitlab origin for GitHub plugin, or different origin for GitHub Gist plugin.

• Git plugins: @github, @gitlab, @bitbucket, @git

zpm load some/plugin,origin:https://github.com/another/origin # This plugin will be loaded from https://github.com/another/origin, but will have internal name some/plugin

zpm load @git/my-plugin,git://my.site/plugin.git # This plugin will be loaded from 3-party origin

• Remote: @gist, @remote

zpm load @gist/user/hash,origin:https://another-site/file.zsh # This file will be downloaded instead of gist
zpm load @remote/plugin,origin:https://mysite.com/plugin.zsh # In this case origin should be declared, because zpm can't detect origin

• Dir: @dir

zpm load @dir/plugin,origin:/home/user/Projects/plugin # Internal plugin directory will be linked to your local directory

• File: @file

zpm load @file/plugin-file,origin:/home/user/Projects/plugin.zsh # Internal plugin file will be linked to your local file

• Some special types, like: @empty, @omz, @omz/theme, @omz/lib

Do not declare own origin:, because this can produce side effects

hook tag

This tag parameter contains command who will be run in the plugin directory after instalation or upgrade

zpm plugin/name,hook:"make; make install"

if and if-not conditions

If condition allows you to run the following commands only if the condition is true

zpm if some-condition (another commands)

Conditions:

• linux - if current OS is Linux
• bsd - if current OS is *BSD
• openwrt - if current OS is OpenWrt
• macos - if current OS is macOS
• termux - if current session run in Termux
• ssh - if session run on remote host
• vte - if session run on VTE based terminal emulator

Result of condition can be negated using if-not tag

The condition can be combined zpm if macos if-not ssh load repo/plugin

Notice: conditions will be verified only at first run, after that will be used generated cache

Upgrade

Run zpm upgrade for upgrading, or run zpm upgrade some-plugin another-plugin if you want to upgrade only these plugins

Clean

By default zpm will generate cache file at first run, but if you will change ~/.zshrc this cache should be removed using zpm clean command

Configuration

You can use another mirror for GitHub/Gitlab/Bitbucket:

# Declare this before zpm load
GITHUB_MIRROR="https://hub.fastgit.org"
GITLAB_MIRROR="Some url"
BITBUCKET_MIRROR="Some url"

Troubleshooting

Powerlevel10k

Powerlevel10k loads extra modules in its installation directory, which it automatically detects by taking the file containing its init code, making it absolute, and taking its directory. However, as zpm combines plugins into one fast-loading cache file, this automatic detection would break.

As a workaround, you have to explicitly tell Powerlevel10k where it is installed. This needs to be done before the cache file is loaded, which means before zpm itself is loaded, like this:

# Adjust the path accordingly if your zpm is not installed at `~/.zpm` or you're
# using a powerlevel10k fork
export POWERLEVEL9K_INSTALLATION_DIR=~/.zpm/plugins/romkatv---powerlevel10k
source ~/.zpm/zpm.zsh

# ...

zpm load romkatv/powerlevel10k

Update to latest zpm

If you have problems with zpm try updating:

rm -rf "${TMPDIR:-/tmp}/zsh-${UID:-user}" # clear the cache
cd ~/.zpm
git pull

Developing process

You can see debug information by setting the system variable DEBUG=zpm

When you make changes, add information about them to the change log in next section. Also add link to pr and link to your GitHub profile.

TODO

• [x] Create logo
• [ ] Improve readme
  • [ ] Describe installation process
• [ ] Improve completions
  • [ ] Now zpm load, zpm upgrade or zpm subcommand will complete only one argument

Changelog

• 6.0

  • Add workarouds for powerlevel10k, zsh-syntax-highlighting, zsh-history-substring-search, sindresorhus/pure

• 5.3

  • Change plugin file path detector

• 5.2

  • Remove old omz tag

• 5.1

  • Change internal functions

• 5.0

  • Removed gen-plugin and gen-completion tags
  • @omz-theme/ and @omz-lib/ changed to @omz/theme/ and @omz/lib/

• 4.2

  • Replace $ZERO with $0. Fixed #43
  • Update README. #44

• 4.1

  • Added possibility to change parallel runner, e.g. GNU Parallel, Rush, Xargs
  • Optimize plugin load
  • Change some plugin urls

• 4.0

  • Refactoring of internal logic
  • Added new plugin types: @gist, @remote

• 3.6

  • Added new plugin types @dir and @file
  • @link now is an alias for @dir
  • Fixed #35

• 3.5

  • Added new logo
  • Added possibility to use mirrors for GitHub/Gitlab/Bitbucket. See issue

• 3.4

  • Added GNU Parallel

• 3.3

  • Added origin tag
  • Removed autoload-all tag

• 3.2

  • Fix plugin load order
  • Use sched for background run

• 3.1

  • Fix completions
  • Add example for @omz

• 3.0

  • Remove unused @link
  • Remove tr calls
  • Deprecate type: tag
  • Internal changes for basename/name,hyperlink
  • Add support for oh-my-zsh themes and libs
  • zpm load @omz-theme/theme-name
  • zpm load @omz-lib/lib
  • Upgrade from 2.x:
  • Add zpm load @omz if you use at least one oh-my-zsh plugin.
  • Replace type:plugin-type with @plugin-type/plugin/name

• 2.3

  • Improve README
  • Remove suppot for zsh_loaded_plugins
  • Add config for Markdownlint

• 2.2

  • Add support for OpenWrt
  • Improve oh-my-zsh-support @igetgames
  • Support for calling plugin functions from command tags @igetgames
  • Fix autoload option processing @igetgames

• 2.1

  • Optimizations
  • Now all content of /functions and /bin will be copied into single dir, in zpm cache dir
  • Change zpm to @zpm
  • Remove unused vars
  • Some vars will be loaded async
  • Fixed colors
  • Notes
  • Now for update zpm need to run zpm u @zpm

• 2.0

  • omz/ prefix replaced by @omz/
  • Added plugin type empty
  • Added autoload and autoload-all tags
  • Added gen-plugin and gen-completion tags
  • Notes:
  • Replace omz/ to @omz/ in your .zshrc