zpm

README

zpm - simple and fast zsh plugins manager

zpm is a plugin manager for zsh designed to be fast and easy to configure.

This tool was designed after seeing other plugin managers as slow or/and inconvenient. Primary design goals when developing this tool were:

• Make it fast;
• Allow to configure it with some conventional format (JSON and YAML are supported);
• Keep .zshrc clean;
• Be able to work with Oh My Zsh plugins;
• Work with updates;
• Make it easily extensible.

This project is largely influenced by Antigen and Antibody.

Contents

• Getting Started
  • Installation
  • Your .zshrc
  • Configuring plugins
  • Installing and updating plugins
• Configuration
• Available commands
• Caching
• Contributing

Getting Started

Installation

You will need go 1.12 to build this project, so please install it and configure Go environment variables. You can follow the official guide.

Then just run go get -u github.com/eugene-babichenko/zpm.

Your .zshrc

Just add this line after you add the directory containing your zpm installation ($GOPATH/bin) into the PATH variable and after you load any completions into the shell.

# Check for updates when starting the shell. Check period can be changed in the
# configuration file. You can remove `--periodic` to run the check every time
# you run a new shell (note that this may slow down the start of your shell). By
# default the check is performed once per day.
zpm check --periodic
# Check if there are plugins, that are list in the config but installed, and
# install them. Remove `--only-missing` if you want to update all of your
# plugins automatically (note that this may slow down the start of your shell).
zpm update --only-missing
# Load plugins into the shell
source <(zpm load)

Configuring plugins

The configuration is located in ~/.zpm.yaml and will be created automatically on the first run. You can change the location of your configuration file using the --config argument.

Here is an example configuration:

Plugins:
- github:zsh-users/zsh-autosuggestions
- github:mafredri/zsh-async
- github:sindresorhus/pure
- oh-my-zsh:plugin:colored-man-pages

You can specify a plugin version if required. Branch names, tags and commit hashes are acceptable. This is available for plugins installed from GitHub and for "oh-my-zsh" plugin line (not for "oh-my-zsh:plugin:*" and "oh-my-zsh:theme:*"!):

Plugins:
- github:marzocchi/zsh-notify@v1.0
- oh-my-zsh@ea3e666e04bfae31b37ef42dfe54801484341e46

JSON is also possible:

{
  "Plugins": [
    "github:zsh-users/zsh-autosuggestions",
    "github:mafredri/zsh-async",
    "github:sindresorhus/pure",
    "oh-my-zsh:plugin:colored-man-pages"
  ]
}

Possible patterns for adding the plugins are:

• github:username/repo for adding plugins from GitHub repositories;
• dir:path/to/plugin for adding local plugins. Note that the path must be relative to the zsh plugins directory (see Configuration).
• file:path/to/file for plugins consisting of a single file. Note that the path must be relative to the zsh plugins directory (see Configuration).
• oh-my-zsh to load Oh My Zsh from GitHub (it is treated specially);
  • oh-my-zsh:plugin:* to load one of the plugins bundled with Oh My Zsh;
  • oh-my-zsh:themes:* to load one of the themes bundled with Oh My Zsh;

Installing and updating plugins

After a plugin has been added to the configuration file, you should run zpm update to download it. This command will also update other plugins. You can run zpm check to check for updates without installing them.

Configuration

This section contains the list of available configuration keys.

• Plugins ([string]) - the list of plugin specifications. The format for specifications is described in Configuring plugins.
• Root (string) - an absolute path at which zpm will install plugins. If left empty, the default location is ~/.zpm on Linux and ~/Library/zpm on macOS.
• LogsPath (string) - an absolute path at which zpm will store logs. If left empty, the default location is ~/.zpm/Logs on Linux and ~/Library/Logs/zpm on macOS.
• UpdateCheckPeriod (string) the period to check for updates. Used when zpm check is called with --periodic. Valid examples are 3h, 30m, 5h30m20s. The default value 24h.
• Logger - logger settings
  • MaxSize (int) - the maximum size of log files in megabytes. The default is 500 MiB.
  • MaxAge (int) - the maximum age of a log file in days. The default value is 28.
  • MaxBackups (int) - the maximum number of log files that are preserved during log rotation. The default value is 6.
  • Level (string) - logging level. Valid values are debug, info, error and fatal. The default value is info.

Available commands

Run zpm help to get the full list of available commands and their flags.

Caching

zpm caches the script that loads plugins for faster loading. This behavior can be disabled by running zpm load with --no-cache. The cache is located in the zpm plugins root directory and is reset when plugins or zpm itself are updated.

Contributing

I appreciate any help! You can submit your questions, proposals and bugs found to the GitHub Issues. Also there is the road map for upcoming features. Feel free to implement any of those if you want!