New: You can request a feature when donating, even fancy or advanced ones get implemented this way. There are
reports about what is being done with the money received.
Table of Contents generated with DocToc
- News
- Zplugin
- Zplugin Wiki
- Installation
- Usage
- Completions
- Zplugin Module
- Hints and Tips
- Getting Help and Community
Here are the new features and updates added to zplugin in the last 90 days.
-
09-08-2019
- A new ice-mod
wrap-track''
which gets;
-separated list of functions that are to be tracked once when executing. In other words you can extend the tracking beyond the moment of loading of a plugin. - The unloading of Zle widgets is now more smart – it takes into account the chains of plugins that can overload the Zle widgets, and solves the interactions that result out of it.
- A new ice-mod
-
29-07-2019
delete
now supports following options:--all
– deletes all plugins and snippets (a purge, similar torm -rf ${ZPLGM[PLUGINS_DIR]} ${ZPLGM[SNIPPETS_DIR]}
)--clean
– deletes only plugins and snippets that are currently not loaded in the current session.
-
09-07-2019
- Zplugin can now have its own plugins, called z-plugins! Check out an example but fully functional z-plugin zdharma/z-p-submods and a document that explains on how to implement your own z-plugin (here).
-
08-07-2019
- You can now do
zplugin ice wait ...
and it will work aszplugin ice wait'0' ...
:) I.e. when there's no value to thewait''
ice then a value of0
is being substituted.
- You can now do
-
02-07-2019
- Cooperation of Fast-Syntax-Highlighting and Zplugin – a new precise highlighting for Zplugin in F-Sy-H.
-
01-07-2019
atclone''
,atpull''
&make''
get run in the same subshell, thus an e.g. export done inatclone''
will be visible during themake
.
-
26-06-2019
notify''
contents gets evaluated, i.e. can contain active code like$(tail -1 /var/log/messages)
, etc.
-
23-06-2019
-
New ice mod
subscribe''
/on-update-of''
which works like thewait''
ice-mod, i.e. defers loading of a plugin, but it looks at modification time of the given file(s), and when it changes, it then triggers loading of the plugin/snippet:% zplugin ice on-update-of'{~/files-*,/tmp/files-*}' lucid \ atload"echo I have been loaded" \ notify"Yes that's true :)" % zplugin load zdharma/null % touch ~/files-1 The plugin has been loaded % Yes that's true :)
The plugin/snippet will be sourced as many times as the file gets updated.
-
-
22-06-2019
-
New ice mod
reset-prompt
that will issuezle .reset-prompt
after loading the plugin or snippet, causing the prompt to be recomputed. Useful with themes & Turbo mode. -
New ice-mod
notify''
which will cause to display an under-prompt notification when the plugin or snippet gets loaded. E.g.:% zplugin ice wait"0" lucid notify"zdharma/null has been loaded" % zplugin light zdharma/null % zdharma/null has been loaded
In case of problems with the loading a warning message will be output:
% zplugin ice notify atload'return 7' % zplugin light zdharma/null % notify: Plugin not loaded / loaded with problem, the return code: 7
Refer to Ice Modifiers section for a complete description.
-
-
29-05-2019
-
Turbo mode, i.e. the
wait''
ice-mode now supports a suffix – the lettera
,b
orc
. The meaning is illustrated by the following example:zplugin ice wait"0b" as"command" pick"wd.sh" atinit"echo Firing 1" lucid zplugin light mfaerevaag/wd zplugin ice wait"0a" as"command" pick"wd.sh" atinit"echo Firing 2" lucid zplugin light mfaerevaag/wd # The output Firing 2 Firing 1
As it can be seen, the second plugin has been loaded first. That's because there are now three sub-slots (the
a
,b
andc
) in which the plugin/snippet loadings can be put into. Plugins from the same time-slot with suffixa
will be loaded before plugins with suffixb
, etc.In other words, instead of
wait'1'
you can enterwait'1a'
,wait'1b'
andwait'1c'
– to this way impose order on the loadings regardless of the order ofzplugin
commands.
-
To see the full history check the changelog.
Zplugin is an elastic and fast Zshell plugin manager that will allow you to install everything from GitHub and other sites.
Zplugin is currently the only plugin manager out there that has Turbo mode which yields 50-73% faster Zsh startup!
Zplugin gives reports from plugin load describing what aliases, functions,
bindkeys, Zle widgets, zstyles, completions, variables, PATH
and FPATH
elements a plugin has set up.
Supported is unloading of plugin and ability to list, (un)install and selectively disable, enable plugin's completions.
The system does not use $FPATH
, loading multiple plugins doesn't clutter
$FPATH
with the same number of entries (e.g. 10
). Code is immune to
KSH_ARRAYS
. Completion management functionality is provided to allow user
to call compinit
only once in .zshrc
.
The information in this README is complemented by the Zplugin wiki. The README is an introductory overview of Zplugin while the wiki gives a complete and in-depth information with examples. Make sure to read it to get the most out of Zplugin.
The easiest way to install Zplugin is to execute:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/tshirotatadashi/zplugin/master/doc/install.sh)"
This will install Zplugin in ~/.zplugin/bin
. .zshrc
will be updated with three
lines of code that will be added to the bottom. The lines will be sourcing
zplugin.zsh
and setting up completion for command zplugin
. After installing and
reloading the shell compile Zplugin with zplugin self-update
.
To manually install Zplugin clone the repo to e.g. ~/.zplugin/bin
:
mkdir ~/.zplugin
git clone https://github.com/tshirotatadashi/zplugin.git ~/.zplugin/bin
and source it from .zshrc
(above compinit):
source ~/.zplugin/bin/zplugin.zsh
If you place the source
below compinit
, then add those two lines after the source
:
autoload -Uz _zplugin
(( ${+_comps} )) && _comps[zplugin]=_zplugin
Various paths can be customized, see section Customizing Paths.
After installing and reloading the shell compile Zplugin with zplugin self-update
.
Click here to read the introduction to Zplugin. It explains basic usage and some of the more unique features of Zplugin such as the Turbo mode. If you're new to Zplugin we highly recommend you read it at least once.
After installing Zplugin you can start adding some actions (load some plugins) to ~/.zshrc
, at bottom. Some examples:
# Two regular plugins loaded without tracking.
zplugin light zsh-users/zsh-autosuggestions
zplugin light zdharma/fast-syntax-highlighting
# Plugin history-search-multi-word loaded with tracking.
zplugin load zdharma/history-search-multi-word
# Load the pure theme, with zsh-async library that's bundled with it.
zplugin ice pick"async.zsh" src"pure.zsh"
zplugin light sindresorhus/pure
# Binary release in archive, from GitHub-releases page.
# After automatic unpacking it provides program "fzf".
zplugin ice from"gh-r" as"program"
zplugin load junegunn/fzf-bin
# One other binary release, it needs renaming from `docker-compose-Linux-x86_64`.
# This is done by ice-mod `mv'{from} -> {to}'. There are multiple packages per
# single version, for OS X, Linux and Windows – so ice-mod `bpick' is used to
# select Linux package – in this case this is actually not needed, Zplugin will
# grep operating system name and architecture automatically when there's no `bpick'.
zplugin ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*"
zplugin load docker/compose
# Vim repository on GitHub – a typical source code that needs compilation – Zplugin
# can manage it for you if you like, run `./configure` and other `make`, etc. stuff.
# Ice-mod `pick` selects a binary program to add to $PATH. You could also install the
# package under the path $ZPFX, see: http://zdharma.org/zplugin/wiki/Compiling-programs
zplugin ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \
atpull"%atclone" make pick"src/vim"
zplugin light vim/vim
# Scripts that are built at install (there's single default make target, "install",
# and it constructs scripts by `cat'ing a few files). The make'' ice could also be:
# `make"install PREFIX=$ZPFX"`, if "install" wouldn't be the only, default target.
zplugin ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX"
zplugin light tj/git-extras
# Handle completions without loading any plugin, see "clist" command.
# This one is to be ran just once, in interactive session.
zplugin creinstall %HOME/my_completions
# For GNU ls (the binaries can be gls, gdircolors, e.g. on OS X when installing the
# coreutils package from Homebrew; you can also use https://github.com/ogham/exa)
zplugin ice atclone"dircolors -b LS_COLORS > c.zsh" atpull'%atclone' pick"c.zsh" nocompile'!'
zplugin light trapd00r/LS_COLORS
You can see an extended explanation of LS_COLORS in the wiki.
# make'!...' -> run make before atclone & atpull
zplugin ice as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' atpull'%atclone' src"zhook.zsh"
zplugin light direnv/direnv
You can see an extended explanation of direnv in the wiki.
If you're interested in more examples then check out the zplugin-configs
repository where users have uploaded their
~/.zshrc
and Zplugin configurations. Feel free to
submit
your ~/.zshrc
there if it contains Zplugin commands.
You can also check out the Gallery of Zplugin Invocations for some additional examples.
Following ice
modifiers are to be passed to zplugin ice ...
to obtain described effects.
The word ice
means something that's added (like ice to a drink) – and in Zplugin it
means adding modifier to a next zplugin
command, and also something that's temporary
because it melts – and this means that the modification will last only for a single
next zplugin
command.
Some Ice-modifiers are highlighted and clicking on them will take you to the appropriate wiki page for an extended explanation.
You may safely assume a given ice works with both plugins and snippets unless explicitly stated otherwise.
Modifier | Description |
---|---|
proto |
Change protocol to git ,ftp ,ftps ,ssh , rsync , etc. Default is https . Does not work with snippets. |
from |
Clone plugin from given site. Supported are from"github" (default), ..."github-rel" , ..."gitlab" , ..."bitbucket" , ..."notabug" (short names: gh , gh-r , gl , bb , nb ). Can also be a full domain name (e.g. for GitHub enterprise). Does not work with snippets. |
ver |
Used with from"gh-r" (i.e. downloading a binary release, e.g. for use with as"program" ) – selects which version to download. Default is latest, can also be explicitly ver"latest" . Works also with regular plugins, checkouts e.g. ver"abranch" , i.e. a specific version. Does not work with snippets. |
bpick |
Used to select which release from GitHub Releases to download, e.g. zplg ice from"gh-r" as"program" bpick"*Darwin*"; zplg load docker/compose . Does not work with snippets. |
depth |
Pass --depth to git , i.e. limit how much of history to download. Does not work with snippets. |
cloneopts |
Pass the contents of cloneopts to git clone . Defaults to --recursive i.e. Change cloning options. Does not work with snippets. |
svn |
Use Subversion for downloading snippet. GitHub supports SVN protocol, this allows to clone subdirectories as snippets, e.g. zplugin ice svn; zplugin snippet OMZ::plugins/git . Other ice pick can be used to select file to source (default are: *.plugin.zsh , init.zsh , *.zsh-theme ). Does not work with plugins. |
Modifier | Description |
---|---|
pick |
Select the file to source, or the file to set as command (when using snippet --command or the ice as"program" ); it is a pattern, alphabetically first matched file is being chosen; e.g. zplugin ice pick"*.plugin.zsh"; zplugin load … . |
src |
Specify additional file to source after sourcing main file or after setting up command (via as"program" ). It is not a pattern but a plain file name. |
multisrc |
Allows to specify multiple files for sourcing, enumerated with spaces as the separators (e.g. multisrc'misc.zsh grep.zsh' ) and also using brace-expansion syntax (e.g. multisrc'{misc,grep}.zsh' ). Supports patterns. |
Modifier | Description |
---|---|
wait |
Postpone loading a plugin or snippet. For wait'1' , loading is done 1 second after prompt. For wait'[[ ... ]]' , wait'(( ... ))' , loading is done when given condition is meet. For wait'!...' , prompt is reset after load. Zsh can start 73% faster thanks to postponed loading. Fact: when wait is used without value, it works as wait'0' . |
load |
A condition to check which should cause plugin to load. It will load once, the condition can be still true, but will not trigger second load (unless plugin is unloaded earlier, see unload below). E.g.: load'[[ $PWD = */github* ]]' . |
unload |
A condition to check causing plugin to unload. It will unload once, then only if loaded again. E.g.: unload'[[ $PWD != */github* ]]' . |
cloneonly |
Don't load the plugin / snippet, only download it |
if |
Load plugin or snippet only when given condition is fulfilled, for example: zplugin ice if'[[ -n "$commands[otool]" ]]'; zplugin load ... . |
has |
Load plugin or snippet only when given command is available (in $PATH), e.g. zplugin ice has'git' ... |
subscribe / on-update-of |
Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. subscribe'{~/files-*,/tmp/files-*}' |
Modifier | Description |
---|---|
silent |
Mute plugin's or snippet's stderr & stdout . Also skip Loaded ... message under prompt for wait , etc. loaded plugins, and completion-installation messages. |
lucid |
Skip Loaded ... message under prompt for wait , etc. loaded plugins (a subset of silent ). |
notify |
Output given message under-prompt after successfully loading a plugin/snippet. In case of problems with the loading, output a warning message and the return code. If starts with ! it will then always output the given message. Hint: if the message is empty, then it will just notify about problems. |
Modifier | Description |
---|---|
blockf |
Disallow plugin to modify fpath . Useful when a plugin wants to provide completions in traditional way. Zplugin can manage completions and plugin can be blocked from exposing them. |
nocompletions |
Don't detect, install and manage completions for this plugin. Completions can be installed later with zplugin creinstall {plugin-spec} . |
Modifier | Description |
---|---|
mv |
Move file after cloning or after update (then, only if new commits were downloaded). Example: mv "fzf-* -> fzf" . It uses -> as separator for old and new file names. Works also with snippets. |
cp |
Copy file after cloning or after update (then, only if new commits were downloaded). Example: cp "docker-c* -> dcompose" . Ran after mv . |
atinit |
Run command after directory setup (cloning, checking it, etc.) of plugin/snippet but before loading. |
atclone |
Run command after cloning, within plugin's directory, e.g. zplugin ice atclone"echo Cloned" . Ran also after downloading snippet. |
atload |
Run command after loading, within plugin's directory. Can be also used with snippets. Passed code can be preceded with ! , it will then be tracked (if using load , not light ). |
atpull |
Run command after updating (only if new commits are waiting for download), within plugin's directory. If starts with "!" then command will be ran before mv & cp ices and before git pull or svn update . Otherwise it is ran after them. Can be atpull'%atclone' , to repeat atclone Ice-mod. |
run-atpull |
Always run the atpull hook (when updating), not only when there are new commits to be downloaded. |
nocd |
Don't switch the current directory into the plugin's directory when evaluating the above ice-mods atinit'' ,atload'' , etc. |
make |
Run make command after cloning/updating and executing mv , cp , atpull , atclone Ice mods. Can obtain argument, e.g. make"install PREFIX=/opt" . If the value starts with ! then make is ran before atclone /atpull , e.g. make'!' . |
Modifier | Description |
---|---|
as |
Can be as"program" (also the alias: as"command" ), and will cause to add script/program to $PATH instead of sourcing (see pick ). Can also be as"completion" – use with plugins or snippets in whose only underscore-starting _* files you are interested in. . |
id-as |
Nickname a plugin or snippet, to e.g. create a short handler for long-url snippet. |
compile |
Pattern (+ possible {...} expansion, like {a/*,b*} ) to select additional files to compile, e.g. compile"(pure|async).zsh" for sindresorhus/pure .</div> |
nocompile |
Don't try to compile pick -pointed files. If passed the exclamation mark (i.e. nocompile'!' ), then do compile, but after make'' and atclone'' (useful if Makefile installs some scripts, to point pick'' at the location of their installation). |
service |
Make following plugin or snippet a service, which will be ran in background, and only in single Zshell instance. See zservices-organization page. |
reset-prompt |
Reset the prompt after loading the plugin/snippet (by issuing zle .reset-prompt ). Note: normally it's sufficient to precede the value of wait'' ice with ! . |
bindmap |
To hold ; -separated strings like Key(s)A -> Key(s)B , e.g. ^R -> ^T; ^A -> ^B . In general, bindmap'' changes bindings (done with the bindkey builtin) the plugin does. The example would cause the plugin to map Ctrl-T instead of Ctrl-R, and Ctrl-B instead of Ctrl-A. Does not work with snippets. |
trackbinds |
Shadow but only bindkey calls even with zplugin light ... , i.e. even with tracking disabled (fast loading), to allow bindmap to remap the key-binds. The same effect has zplugin light -b ... , i.e. additional -b option to the light -subcommand. Does not work with snippets. |
wrap-track |
Takes a ; -separated list of function names that are to be tracked (meaning gathering report and unload data) once during execution. It works by wrapping the functions with a tracking-enabling and disabling snippet of code. In summary, wrap-track allows to extend the tracking beyond the moment of loading of a plugin. Example use is to wrap-track a precmd function of a prompt (like _p9k_precmd() of powerlevel10k) or other plugin that postpones its initialization till the first prompt (like e.g.: zsh-autosuggestions). Does not work with snippets. |
Order of execution of related Ice-mods: atinit
-> atpull!
-> make'!!'
-> mv
-> cp
-> make!
-> atclone
/atpull
-> make
-> (plugin script loading)
-> src
-> multisrc
-> atload
.
Following commands are passed to zplugin ...
to obtain described effects.
Command | Description |
---|---|
-h, --help, help |
Usage information. |
man |
Manual. |
Command | Description |
---|---|
load {plg-spec} |
Load plugin, can also receive absolute local path. |
light [-b] {plg-spec} |
Light plugin load, without reporting/tracking. -b – track bindkey -calls only. |
unload [-q] {plg-spec} |
Unload plugin loaded with zplugin load ... . -q – quiet. |
snippet [-f] {url} |
Source local or remote file (by direct URL). -f – don't use cache (force redownload). |
Command | Description |
---|---|
clist, completions |
List completions in use. |
cdisable {cname} |
Disable completion cname . |
cenable {cname} |
Enable completion cname . |
creinstall [-q] {plg-spec} |
Install completions for plugin, can also receive absolute local path. -q – quiet. |
cuninstall {plg-spec} |
Uninstall completions for plugin. |
csearch |
Search for available completions from any plugin. |
compinit |
Refresh installed completions. |
cclear |
Clear stray and improper completions. |
cdlist |
Show compdef replay list. |
cdreplay [-q] |
Replay compdefs (to be done after compinit). -q – quiet. |
cdclear [-q] |
Clear compdef replay list. -q – quiet. |
Command | Description |
---|---|
dtrace, dstart |
Start tracking what's going on in session. |
dstop |
Stop tracking what's going on in session. |
dunload |
Revert changes recorded between dstart and dstop. |
dreport |
Report what was going on in session. |
dclear |
Clear report of what was going on in session. |
Command | Description |
---|---|
times [-s] |
Statistics on plugin load times, sorted in order of loading. -s – use seconds instead of milliseconds. |
zstatus |
Overall Zplugin status. |
report {plg-spec}|--all |
Show plugin report. --all – do it for all plugins. |
loaded [keyword], list [keyword] |
Show what plugins are loaded (filter with 'keyword'). |
ls |
List snippets in formatted and colorized manner. |
status {plg-spec}|URL|--all |
Git status for plugin or svn status for snippet. --all – do it for all plugins and snippets. |
recently [time-spec] |
Show plugins that changed recently, argument is e.g. 1 month 2 days. |
bindkeys |
Lists bindkeys set up by each plugin. |
Command | Description |
---|---|
compile {plg-spec}|--all |
Compile plugin. --all – compile all plugins. |
uncompile {plg-spec}|--all |
Remove compiled version of plugin. --all – do it for all plugins. |
compiled |
List plugins that are compiled. |
Command | Description |
---|---|
self-update |
Updates and compiles Zplugin. |
update [-q] [-r] {plg-spec}|URL|--all |
Git update plugin or snippet. --all – update all plugins and snippets. -q – quiet. -r | --reset – run git reset before doing the update. --hard – svn revert before pulling changes |
ice <ice specification> |
Add ice to next command, argument is e.g. from"gitlab". |
delete {plg-spec}|URL|--clean|--all |
Remove plugin or snippet from disk (good to forget wrongly passed ice-mods). --all – purge. --clean – delete plugins and snippets that are not loaded. |
cd {plg-spec} |
Cd into plugin's directory. Also support snippets if fed with URL. |
edit {plg-spec} |
Edit plugin's file with $EDITOR. |
glance {plg-spec} |
Look at plugin's source (pygmentize, {,source-}highlight). |
stress {plg-spec} |
Test plugin for compatibility with set of options. |
changes {plg-spec} |
View plugin's git log. |
create {plg-spec} |
Create plugin (also together with GitHub repository). |
srv {service-id} [cmd] |
Control a service, command can be: stop,start,restart,next,quit; next moves the service to another Zshell. |
recall {plg-spec}|URL |
Fetch saved ice modifiers and construct zplugin ice ... command. |
env-whitelist [-v] [-h] {env..} |
Allows to specify names (also patterns) of variables left unchanged during an unload. -v – verbose. |
module |
Manage binary Zsh module shipped with Zplugin, see zplugin module help . |
To update Zplugin issue zplugin self-update
in the command line.
To update all plugins and snippets, issue zplugin update
. If you wish to update only
a single plugin/snippet instead issue zplugin update NAME_OF_PLUGIN
. A list of
commits will be shown:
Some plugins require performing an action each time they're updated. One way you can do
this is by using the atpull
ice modifier. For example, writing zplugin ice atpull'./configure'
before loading a plugin will execute ./configure
after a successful update. Refer to Ice Modifiers for more information.
To use themes created for Oh My Zsh you might want to first source the git
library there:
zplugin snippet http://github.com/robbyrussell/oh-my-zsh/raw/master/lib/git.zsh
# Or using OMZ:: shorthand:
zplugin snippet OMZ::lib/git.zsh
If the library will not be loaded, then similar to following errors will be appearing:
........:1: command not found: git_prompt_status
........:1: command not found: git_prompt_short_sha
Then you can use the themes as snippets (zplugin snippet {file path or GitHub URL}
).
Some themes require not only Oh My Zsh's Git library, but also Git plugin (error
about current_branch
function can be appearing). Load this Git-plugin as single-file
snippet directly from OMZ:
zplugin snippet OMZ::plugins/git/git.plugin.zsh
Such lines should be added to .zshrc
. Snippets are cached locally, use -f
option to download
a fresh version of a snippet, or zplugin update {URL}
. Can also use zplugin update --all
to
update all snippets (and plugins).
Most themes require promptsubst
option (setopt promptsubst
in zshrc
), if it isn't set, then
prompt will appear as something like: ... $(build_prompt) ...
.
You might want to suppress completions provided by the git plugin by issuing zplugin cdclear -q
(-q
is for quiet) – see below Ignoring Compdefs.
To summarize:
# Load OMZ Git library
zplugin snippet OMZ::lib/git.zsh
# Load Git plugin from OMZ
zplugin snippet OMZ::plugins/git/git.plugin.zsh
zplugin cdclear -q # <- forget completions provided up to this moment
setopt promptsubst
# Load theme from OMZ
zplugin snippet OMZ::themes/dstufft.zsh-theme
# Load normal GitHub plugin with theme depending on OMZ Git library
zplugin light NicoSantangelo/Alpharized
See also the Wiki page: Example Oh My Zsh Setup.
With no Turbo mode in use, compinit can be called normally, i.e.: as autoload compinit; compinit
. This should be done after loading of all plugins and before possibly calling
zplugin cdreplay
. Also, plugins aren't allowed to simply run compdefs
. You can
decide whether to run compdefs
by issuing zplugin cdreplay
(reads: compdef
-replay).
To summarize:
source ~/.zplugin/bin/zplugin.zsh
zplugin load "some/plugin"
...
compdef _gnu_generic fd # this will be intercepted by Zplugin, because as the compinit
# isn't yet loaded, thus there's no such function `compdef'; yet
# Zplugin provides its own `compdef' function which saves the
# completion-definition for later possible re-run with `zplugin
# cdreplay` or `zpcdreplay` (the second one can be used in hooks
# like atload'', atinit'', etc.)
...
zplugin load "other/plugin"
autoload -Uz compinit
compinit
zplugin cdreplay -q # -q is for quiet; actually run all the `compdef's saved before
#`compinit` call (`compinit' declares the `compdef' function, so
# it cannot be used until `compinit` is ran; Zplugin solves this
# via intercepting the `compdef'-calls and storing them for later
# use with `zplugin cdreplay')
This allows to call compinit once.
Performance gains are huge, example shell startup time with double compinit
: 0.980 sec, with
cdreplay
and single compinit
: 0.156 sec.
If you load completions using wait''
Turbo mode then you can add
atinit'zpcompinit'
to syntax-highlighting plugin (which should be the last
one loaded, as their (2 projects, z-sy-h &
f-sy-h)
documentation state), or atload'zpcompinit'
to last
completion-related plugin. zpcompinit
is a function that just runs autoload compinit; compinit
, created for convenience. There's also zpcdreplay
which
will replay any caught compdefs so you can also do: atinit'zpcompinit; zpcdreplay'
, etc. Basically, the whole topic is the same as normal compinit
call,
but it is done in atinit
or atload
hook of the last related plugin with use of the
helper functions (zpcompinit
,zpcdreplay
& zpcdclear
– see below for explanation
of the last one).
If you want to ignore compdefs provided by some plugins or snippets, place their load commands
before commands loading other plugins or snippets, and issue zplugin cdclear
(or
zpcdclear
, designed to be used in hooks like atload''
):
source ~/.zplugin/bin/zplugin.zsh
zplugin snippet OMZ::plugins/git/git.plugin.zsh
zplugin cdclear -q # <- forget completions provided by Git plugin
zplugin load "some/plugin"
...
zplugin load "other/plugin"
autoload -Uz compinit
compinit
zplugin cdreplay -q # <- execute compdefs provided by rest of plugins
zplugin cdlist # look at gathered compdefs
On Ubuntu users might get surprised that e.g. their completions work while they didn't
call compinit
in their .zshrc
. That's because the function is being called in
/etc/zshrc
. To disable this call – what is needed to avoid the slowdown and if user
loads any completion-equipped plugins, i.e. almost on 100% – add the following lines to
~/.zshenv
:
# Skip the not really helping Ubuntu global compinit
skip_global_compinit=1
The module is a binary Zsh module (think about zmodload
Zsh command, it's that topic) which transparently and
automatically compiles sourced scripts. Many plugin managers do not offer compilation of plugins, the module is
a solution to this. Even if a plugin manager does compile plugin's main script (like Zplugin does), the script can
source smaller helper scripts or dependency libraries (for example, the prompt geometry-zsh/geometry
does that)
and there are very few solutions to that, which are demanding (e.g. specifying all helper files in plugin load
command and tracking updates to the plugin – in Zplugin case: by using compile
ice-mod).
To install just the binary Zplugin module standalone (Zplugin is not needed, the module can be used with any other plugin manager), execute:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/tshirotatadashi/zplugin/master/doc/mod-install.sh)"
This script will display what to add to ~/.zshrc
(2 lines) and show usage instructions.
Zplugin users can build the module by issuing following command instead of running above mod-install.sh
script
(the script is for e.g. zgen
users or users of any other plugin manager):
zplugin module build
This command will compile the module and display instructions on what to add to ~/.zshrc
.
Besides the compilation-feature, the module also measures duration of each script sourcing. Issue zpmod source-study
after loading the module at top of ~/.zshrc
to see a list of all sourced files with the time the
sourcing took in milliseconds on the left. This feature allows to profile the shell startup. Also, no script can
pass-through that check and you will obtain a complete list of all loaded scripts, like if Zshell itself was
tracking this. The list can be surprising.
To enable debug messages from the module set:
typeset -g ZPLG_MOD_DEBUG=1
Following variables can be set to custom values, before sourcing Zplugin. The
previous global variables like $ZPLG_HOME
have been removed to not pollute
the namespace – there's single $ZPLGM
("ZPLUGIN MAP") hash instead of 8
string
variables. Please update your dotfiles.
declare -A ZPLGM # initial Zplugin's hash definition, if configuring before loading Zplugin, and then:
Hash Field | Description |
---|---|
ZPLGM[BIN_DIR] | Where Zplugin code resides, e.g.: "~/.zplugin/bin" |
ZPLGM[HOME_DIR] | Where Zplugin should create all working directories, e.g.: "~/.zplugin" |
ZPLGM[PLUGINS_DIR] | Override single working directory – for plugins, e.g. "/opt/zsh/zplugin/plugins" |
ZPLGM[COMPLETIONS_DIR] | As above, but for completion files, e.g. "/opt/zsh/zplugin/root_completions" |
ZPLGM[SNIPPETS_DIR] | As above, but for snippets |
ZPLGM[ZCOMPDUMP_PATH] | Path to .zcompdump file, with the file included (i.e. it's name can be different) |
ZPLGM[COMPINIT_OPTS] | Options for compinit call (i.e. done by zpcompinit ), use to pass -C to speed up loading |
ZPLGM[MUTE_WARNINGS] | If set to 1 , then mutes some of the Zplugin warnings, specifically the plugin already registered warning |
There is also $ZPFX
, set by default to ~/.zplugin/polaris
– a directory
where software with Makefile
, etc. can be pointed to, by e.g. atclone'./configure --prefix=$ZPFX'
.
Use create
subcommand with user name _local
(the default) to create plugin's
skeleton in $ZPLGM[PLUGINS_DIR]
. It will be not connected with GitHub repository
(because of user name being _local
). To enter the plugin's directory use cd
command
with just plugin's name (without _local
, it's optional).
If user name will not be _local
, then Zplugin will create repository also on GitHub
and setup correct repository origin.
There are several projects that provide git extensions. Installing them with Zplugin has many benefits:
- all files are under
$HOME
– no administrator rights needed, - declarative setup (like Chef or Puppet) – copying
.zshrc
to different account brings also git-related setup, - easy update by e.g.
zplugin update --all
.
Below is a configuration that adds multiple git extensions, loaded in Turbo mode, two seconds after prompt:
zplugin ice wait"2" lucid as"program" pick"bin/git-dsf"
zplugin light zdharma/zsh-diff-so-fancy
zplugin ice wait"2" lucid as"program" pick"$ZPFX/bin/git-now" make"prefix=$ZPFX install"
zplugin light iwata/git-now
zplugin ice wait"2" lucid as"program" pick"$ZPFX/bin/git-alias" make"PREFIX=$ZPFX" nocompile
zplugin light tj/git-extras
zplugin ice wait"2" lucid as"program" atclone'perl Makefile.PL PREFIX=$ZPFX' atpull'%atclone' \
make'install' pick"$ZPFX/bin/git-cal"
zplugin light k4rthik/git-cal
Target directory for installed files is $ZPFX
(~/.zplugin/polaris
by default).
Do you need help or wish to get in touch with other Zplugin users?
-
Visit our subreddit r/zplugin.
-
Chat with us in our IRC channel. Connect to chat.freenode.net:6697 (SSL) or chat.freenode.net:6667 and join #zplugin.