zsh/zdharma-continuum.zinit
1
0
Fork 0
mirror of https://github.com/zdharma-continuum/zinit.git synced 2026-09-10 07:36:38 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat: display version via version sub command

Browse source 
Signed-off-by: Vladislav Doster <mvdoster@gmail.com>
This commit is contained in:
Vladislav Doster 2022-12-16 16:09:37 +00:00
parent 59975d70d7
commit bfb01e65d7
8 changed files with 265 additions and 186 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/linting.yaml vendored
View file

@ -33,7 +33,7 @@ jobs:
# run: commitlint --from=$(git cherry origin/main | head -n 1 | awk '{print $2}')
- name: markdown
run: find . -name '*.md' ! -name 'CHANGELOG.md' -name '*.md' -type f -print0 | xargs -0 -n1 -P4 mdformat --check --wrap 120
run: find . -name '*.md' ! -name 'CHANGELOG.md' -type f -print0 | xargs -0 -n1 -P4 mdformat --check --wrap 120 --number
# - name: shell (shfmt)
# run: find . -name '*.sh' -type f -print0 | xargs -0 -n1 -P4 shfmt -bn -ci -d -i 2 -ln bash -s -sr

289
README.md
View file

@ -9,6 +9,8 @@ # Zinit<a name="zinit"></a>
[![MIT License][mit-badge]][mit-link] [![zinit version][ver-badge]][ver-link] [![zunit tests][tests-badge]][tests-link]
[![Join the chat at https://gitter.im/zdharma-continuum/zinit][gitter-badge]][gitter-link]
[hello][gitter-link]
<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=2 -->
- [Zinit Wiki](#zinit-wiki)
@ -73,27 +75,27 @@ # Zinit<a name="zinit"></a>
(i.e., the shell will start up to **5** times faster!). Check out a speed comparison with other popular plugin
managers [here](https://github.com/zdharma-continuum/pm-perf-test).
1. The plugin manager gives **reports** from plugin loadings describing what **aliases**, functions, **bindkeys**, Zle
2. The plugin manager gives **reports** from plugin loadings describing what **aliases**, functions, **bindkeys**, Zle
widgets, zstyles, **completions**, variables, `PATH` and `FPATH` elements a plugin has set up. This allows one to
quickly familiarize oneself with a new plugin and provides rich and easy-to-digest information which might be helpful
on various occasions.
1. Supported is the unloading of plugin and ability to list, (un)install and **selectively disable**, **enable**
3. Supported is the unloading of plugin and ability to list, (un)install and **selectively disable**, **enable**
plugin's completions.
1. The plugin manager supports loading plugins and libraries from Oh My Zsh or Prezto. However, the implementation isn't
4. The plugin manager supports loading plugins and libraries from Oh My Zsh or Prezto. However, the implementation isn't
framework-specific and doesn't bloat the plugin manager with such code (more on this topic can be found on the Wiki,
in the [Introduction](https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/#oh_my_zsh_prezto)).
1. The system does not use `$FPATH`, loading multiple plugins doesn't clutter `$FPATH` with the same number of entries
5. The system does not use `$FPATH`, loading multiple plugins doesn't clutter `$FPATH` with the same number of entries
(e.g. `10`, `15` or more). Code is immune to `KSH_ARRAYS` and other options typically causing compatibility problems.
1. Zinit supports special, dedicated **packages** that offload the user from providing long and complex commands. See
6. Zinit supports special, dedicated **packages** that offload the user from providing long and complex commands. See
the [zinit-packages repository](https://github.com/zdharma-continuum/zinit-packages) for a growing, complete list of
Zinit packages and the [Wiki page](https://zdharma-continuum.github.io/zinit/wiki/Zinit-Packages/) for an article
about the feature.
1. Also, specialized Zinit extensions — called **annexes** — have the ability to extend the plugin manager with new
7. Also, specialized Zinit extensions — called **annexes** — have the ability to extend the plugin manager with new
commands, URL-preprocessors (used by e.g.:
[zinit-annex-readurl](https://github.com/zdharma-continuum/zinit-annex-readurl) annex), post-install and post-update
hooks, and much more. See the [zdharma-continuum](https://github.com/zdharma-continuum) organization for a growing,
@ -398,7 +400,7 @@ ## Zinit Setting
### Use `zi ice svn` if a plugin/snippet requires an entire subdirectory<a name="use-zi-ice-svn-if-a-pluginsnippet-requires-an-entire-subdirectory"></a>
1. [gitfast](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/gitfast)
1. [osx](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/osx)
2. [osx](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/osx)
```zsh
zi ice svn
@ -411,7 +413,7 @@ ### Use `zi ice svn` if a plugin/snippet requires an entire subdirectory<a name=
### Use `zi ice as'completion'` to directly add single file completion snippets<a name="use-zi-ice-ascompletion-to-directly-add-single-file-completion-snippets"></a>
1. [docker](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker)
1. [fd](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/fd)
2. [fd](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/fd)
```zsh
zi ice as"completion"
@ -688,99 +690,99 @@ ## Ice Modifiers<a name="ice-modifiers"></a>
### Cloning Options<a name="cloning-options"></a>
| Modifier | Description |
| :--------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `proto` | <div align="justify" style="text-align: justify;">Change protocol to `git`,`ftp`,`ftps`,`ssh`, `rsync`, etc. Default is `https`. **Does not work with snippets.** </div> |
| [**`from`**](https://zdharma-continuum.github.io/zinit/wiki/Private-Repositories/) | <div align="justify" style="text-align: justify;">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.**</div> |
| `ver` | <div align="justify" style="text-align: justify;">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 and packages (`pack` ice) checkouts e.g. `ver"abranch"`, i.e. a specific version. **Does not work with snippets.**</div> |
| `bpick` | <div align="justify" style="text-align: justify;">Used to select which release from GitHub Releases to download, e.g. `zini ice from"gh-r" as"program" bpick"*Darwin*"; zini load docker/compose`. **Does not work with snippets.** </div> |
| `depth` | <div align="justify" style="text-align: justify;">Pass `--depth` to `git`, i.e. limit how much of history to download. **Does not work with snippets.**</div> |
| `cloneopts` | <div align="justify" style="text-align: justify;">Pass the contents of `cloneopts` to `git clone`. Defaults to `--recursive`. I.e.: change cloning options. Pass empty ice to disable recursive cloning. **Does not work with snippets.** </div> |
| `pullopts` | <div align="justify" style="text-align: justify;">Pass the contents of `pullopts` to `git pull` used when updating plugins. **Does not work with snippets.** </div> |
| `svn` | <div align="justify" style="text-align: justify;">Use Subversion for downloading snippet. GitHub supports `SVN` protocol, this allows to clone subdirectories as snippets, e.g. `zinit ice svn; zinit snippet OMZP::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.**</div> |
| Modifier | Description |
| :---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bpick` | Used to select which release from GitHub Releases to download, e.g. `zini ice from"gh-r" as"program" bpick"*Darwin*"; zini load docker/compose`. **Does not work with snippets.** |
| `cloneopts` | Pass the contents of `cloneopts` to `git clone`. Defaults to `--recursive`. I.e.: change cloning options. Pass empty ice to disable recursive cloning. **Does not work with snippets.** |
| `depth` | Pass `--depth` to `git`, i.e. limit how much of history to download. **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.** |
| `proto` | Change protocol to `git`,`ftp`,`ftps`,`ssh`, `rsync`, etc. Default is `https`. **Does not work with snippets.** |
| `pullopts` | Pass the contents of `pullopts` to `git pull` used when updating plugins. **Does not work with snippets.** |
| `svn` | Use Subversion for downloading snippet. GitHub supports `SVN` protocol, this allows to clone subdirectories as snippets, e.g. `zinit ice svn; zinit snippet OMZP::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.** |
| `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 and packages (`pack` ice) checkouts e.g. `ver"abranch"`, i.e. a specific version. **Does not work with snippets.** |
### Selection of Files (To Source, …)<a name="selection-of-files-to-source-%E2%80%A6"></a>
| Modifier | Description |
| :--------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**`pick`**](https://zdharma-continuum.github.io/zinit/wiki/Sourcing-multiple-files/) | <div align="justify" style="text-align: justify;">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. `zinit ice pick"*.plugin.zsh"; zinit load …`.</div> |
| [**`src`**](https://zdharma-continuum.github.io/zinit/wiki/Sourcing-multiple-files) | <div align="justify" style="text-align: justify;">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.</div> |
| [**`multisrc`**](https://zdharma-continuum.github.io/zinit/wiki/Sourcing-multiple-files) | <div align="justify" style="text-align: justify;">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.</div> |
| Modifier | Description |
| :--------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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. |
| `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. `zinit ice pick"*.plugin.zsh"; zinit 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. |
### Conditional Loading<a name="conditional-loading"></a>
| Modifier | Description |
| :----------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**`wait`**](https://zdharma-continuum.github.io/zinit/wiki/Example-wait-conditions) | <div align="justify" style="text-align: justify;">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 80% (i.e.: 5x) faster thanks to postponed loading. **Fact:** when `wait` is used without value, it works as `wait'0'`.</div> |
| [**`load`**](https://zdharma-continuum.github.io/zinit/wiki/Multiple-prompts) | <div align="justify" style="text-align: justify;">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* ]]'`.</div> |
| [**`unload`**](https://zdharma-continuum.github.io/zinit/wiki/Multiple-prompts) | <div align="justify" style="text-align: justify;">A condition to check causing plugin to unload. It will unload once, then only if loaded again. E.g.: `unload'[[ $PWD != */github* ]]'`.</div> |
| `cloneonly` | <div align="justify" style="text-align: justify;">Don't load the plugin / snippet, only download it </div> |
| `if` | <div align="justify" style="text-align: justify;">Load plugin or snippet only when given condition is fulfilled, for example: `zinit ice if'[[ -n "$commands[otool]" ]]'; zinit load ...`.</div> |
| `has` | <div align="justify" style="text-align: justify;">Load plugin or snippet only when given command is available (in $PATH), e.g. `zinit ice has'git' ...` </div> |
| `subscribe` / `on-update-of` | <div align="justify" style="text-align: justify;">Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. `subscribe'{~/files-*,/tmp/files-*}'` </div> |
| `trigger-load` | <div align="justify" style="text-align: justify;">Creates a function that loads the associated plugin/snippet, with an option (to use it, precede the ice content with `!`) to automatically forward the call afterwards, to a command of the same name as the function. Can obtain multiple functions to create – sparate with `;`.</div> |
| Modifier | Description |
| :--------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cloneonly` | Don't load the plugin / snippet, only download it |
| `has` | Load plugin or snippet only when given command is available (in $PATH), e.g. `zinit ice has'git' ...` |
| `if` | Load plugin or snippet only when given condition is fulfilled, for example: `zinit ice if'[[ -n "$commands[otool]" ]]'; zinit load ...`. |
| `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* ]]'`. |
| `subscribe` / `on-update-of` | Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. `subscribe'{~/files-*,/tmp/files-*}'` |
| `trigger-load` | Creates a function that loads the associated plugin/snippet, with an option (to use it, precede the ice content with `!`) to automatically forward the call afterwards, to a command of the same name as the function. Can obtain multiple functions to create – sparate with `;`. |
| `unload` | A condition to check causing plugin to unload. It will unload once, then only if loaded again. E.g.: `unload'[[ $PWD != */github* ]]'`. |
| `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 80% (i.e.: 5x) faster thanks to postponed loading. **Fact:** when `wait` is used without value, it works as `wait'0'`. |
### Plugin Output<a name="plugin-output"></a>
| Modifier | Description |
| :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `silent` | <div align="justify" style="text-align: justify;">Mute plugin's or snippet's `stderr` & `stdout`. Also skip `Loaded ...` message under prompt for `wait`, etc. loaded plugins, and completion-installation messages.</div> |
| `lucid` | <div align="justify" style="text-align: justify;">Skip `Loaded ...` message under prompt for `wait`, etc. loaded plugins (a subset of `silent`).</div> |
| `notify` | <div align="justify" style="text-align: justify;">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.</div> |
| Modifier | Description |
| :------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `silent` | Mute plugin's or snippet's `stderr` & `stdout`. Also skip `Loaded ...` message under prompt for `wait`, etc. loaded plugins, and completion-installation messages. |
### Completions<a name="completions"></a>
| Modifier | Description |
| :-------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockf` | <div align="justify" style="text-align: justify;">Disallow plugin to modify `fpath`. Useful when a plugin wants to provide completions in traditional way. Zinit can manage completions and plugin can be blocked from exposing them.</div> |
| `nocompletions` | <div align="justify" style="text-align: justify;">Don't detect, install and manage completions for this plugin. Completions can be installed later with `zinit creinstall {plugin-spec}`.</div> |
| `completions` | <div align="justify" style="text-align: justify;">Do detect, install and manage completions for this plugin. Overwrites `as'null'` or `nocompletions`.</div> |
| Modifier | Description |
| :-------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockf` | Disallow plugin to modify `fpath`. Useful when a plugin wants to provide completions in traditional way. Zinit can manage completions and plugin can be blocked from exposing them. |
| `completions` | Do detect, install and manage completions for this plugin. Overwrites `as'null'` or `nocompletions`. |
| `nocompletions` | Don't detect, install and manage completions for this plugin. Completions can be installed later with `zinit creinstall {plugin-spec}`. |
### Command Execution After Cloning, Updating or Loading<a name="command-execution-after-cloning-updating-or-loading"></a>
| Modifier | Description |
| :--------------------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mv` | <div align="justify" style="text-align: justify;">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.</div> |
| `cp` | <div align="justify" style="text-align: justify;">Copy file after cloning or after update (then, only if new commits were downloaded). Example: `cp "docker-c* -> dcompose"`. Ran after `mv`.</div> |
| [**`atclone`**](https://zdharma-continuum.github.io/zinit/wiki/atload-and-other-at-ices) | <div align="justify" style="text-align: justify;">Run command after cloning, within plugin's directory, e.g. `zinit ice atclone"echo Cloned"`. Ran also after downloading snippet.</div> |
| [**`atpull`**](https://zdharma-continuum.github.io/zinit/wiki/atload-and-other-at-ices) | <div align="justify" style="text-align: justify;">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.</div> |
| [**`atinit`**](https://zdharma-continuum.github.io/zinit/wiki/atload-and-other-at-ices) | <div align="justify" style="text-align: justify;">Run command after directory setup (cloning, checking it, etc.) of plugin/snippet but before loading.</div> |
| [**`atload`**](https://zdharma-continuum.github.io/zinit/wiki/atload-and-other-at-ices) | <div align="justify" style="text-align: justify;">Run command after loading, within plugin's directory. Can be also used with snippets. Passed code can be preceded with `!`, it will then be investigated (if using `load`, not `light`).</div> |
| `run-atpull` | <div align="justify" style="text-align: justify;">Always run the atpull hook (when updating), not only when there are new commits to be downloaded.</div> |
| `nocd` | <div align="justify" style="text-align: justify;">Don't switch the current directory into the plugin's directory when evaluating the above ice-mods `atinit''`,`atload''`, etc.</div> |
| `configure` | <div align="justify" style="text-align: justify;">Runs `./configure` script and by default changes the installation directory by passing `--prefix=$ZPFX` to the script. Runs before `make''` and after `make'!'`, you can pass `'!'` too to this ice (i.e.: `configure'!'`) to make it execute earlier – before `make'!'` and after `make'!!'`. If `#` given in the ice value then also executes script `./autogen.sh` first before running `./configure`. The script is run anyway if there is no `configure` script. Also, when there exist another build-system related files, then it is run if no `configure` script is found. Currently supported systems are: CMake, scons and meson, checked-for/run in this order</div> |
| [**`make`**](https://zdharma-continuum.github.io/zinit/wiki/Installing-with-make) | <div align="justify" style="text-align: justify;">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'!'`.</div> |
| `countdown` | <div align="justify" style="text-alignq: justify;">Causes an interruptable (by Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing `atclone''`,`atpull''` and `make` ices</div> |
| `reset` | <div align="justify" style="text-align: justify;">Invokes `git reset --hard HEAD` for plugins or `svn revert` for SVN snippets before pulling any new changes. This way `git` or `svn` will not report conflicts if some changes were done in e.g.: `atclone''` ice. For file snippets and `gh-r` plugins it invokes `rm -rf *`.</div> |
| Modifier | Description |
| :----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `atclone` | Run command after cloning, within plugin's directory, e.g. `zinit ice atclone"echo Cloned"`. Ran also after downloading snippet. |
| `atinit` | Run command after directory setup (cloning, checking it, etc.) of plugin/snippet but before loading. |
| `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 investigated (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. |
| `configure` | Runs `./configure` script and by default changes the installation directory by passing `--prefix=$ZPFX` to the script. Runs before `make''` and after `make'!'`, you can pass `'!'` too to this ice (i.e.: `configure'!'`) to make it execute earlier – before `make'!'` and after `make'!!'`. If `#` given in the ice value then also executes script `./autogen.sh` first before running `./configure`. The script is run anyway if there is no `configure` script. Also, when there exist another build-system related files, then it is run if no `configure` script is found. Currently supported systems are: CMake, scons and meson, checked-for/run in this order |
| `countdown` | Causes an interruptable (by Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing `atclone''`,`atpull''` and `make` ices |
| `cp` | Copy file after cloning or after update (then, only if new commits were downloaded). Example: `cp "docker-c* -> dcompose"`. Ran after `mv`. |
| `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'!'`. |
| `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. |
| `nocd` | Don't switch the current directory into the plugin's directory when evaluating the above ice-mods `atinit''`,`atload''`, etc. |
| `reset` | Invokes `git reset --hard HEAD` for plugins or `svn revert` for SVN snippets before pulling any new changes. This way `git` or `svn` will not report conflicts if some changes were done in e.g.: `atclone''` ice. For file snippets and `gh-r` plugins it invokes `rm -rf *`. |
| `run-atpull` | Always run the atpull hook (when updating), not only when there are new commits to be downloaded. |
### Sticky-Emulation Of Other Shells<a name="sticky-emulation-of-other-shells"></a>
| Modifier | Description |
| :-------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sh`, `!sh` | <div align="justify" style="text-align: justify;">Source the plugin's (or snippet's) script with `sh` emulation so that also all functions declared within the file will get a *sticky* emulation assigned – when invoked they'll execute also with the `sh` emulation set-up. The `!sh` version switches additional options that are rather not important from the portability perspective.</div> |
| `bash`, `!bash` | <div align="justify" style="text-align: justify;">The same as `sh`, but with the `SH_GLOB` option disabled, so that Bash regular expressions work.</div> |
| `ksh`, `!ksh` | <div align="justify" style="text-align: justify;">The same as `sh`, but emulating `ksh` shell.</div> |
| `csh`, `!csh` | <div align="justify" style="text-align: justify;">The same as `sh`, but emulating `csh` shell.</div> |
| Modifier | Description |
| :------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sh`/`!sh` | Source the plugin's (or snippet's) script with `sh` emulation so that also all functions declared within the file will get a *sticky* emulation assigned – when invoked they'll execute also with the `sh` emulation set-up. The `!sh` version switches additional options that are rather not important from the portability perspective. |
| `csh`/`!csh` | The same as `sh`, but emulating `csh` shell. |
| `ksh`/`!ksh` | The same as `sh`, but emulating `ksh` shell. |
| `bash`/`!bash` | The same as `sh`, but with the `SH_GLOB` option disabled, so that Bash regular expressions work. |
### Others<a name="others"></a>
| Modifier | Description |
| :---------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as` | <div align="justify" style="text-align: justify;">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. The third possible value is `as"null"` – a shorthand for `pick"/dev/null" nocompletions` – i.e.: it disables the default script-file sourcing and also the installation of completions.</div> |
| [**`id-as`**](https://zdharma-continuum.github.io/zinit/wiki/id-as/) | <div align="justify" style="text-align: justify;">Nickname a plugin or snippet, to e.g. create a short handler for long-url snippet.</div> |
| `compile` | <div align="justify" style="text-align: justify;">Pattern (+ possible `{...}` expansion, like `{a/*,b*}`) to select additional files to compile, e.g. `compile"(pure\|async).zsh"` for `sindresorhus/pure`.</div> |
| `nocompile` | <div align="justify" style="text-align: justify;">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).</div> |
| `service` | <div align="justify" style="text-align: justify;">Make following plugin or snippet a *service*, which will be ran in background, and only in single Zshell instance. See [the zservice-\* repositories](https://github.com/orgs/zdharma-continuum/repositories?q=zservice-).</div> |
| `reset-prompt` | <div align="justify" style="text-align: justify;">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 `!`.</div> |
| `bindmap` | <div align="justify" style="text-align: justify;">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.**</div> |
| `trackbinds` | <div align="justify" style="text-align: justify;">Shadow but only `bindkey` calls even with `zinit light ...`, i.e. even with investigating disabled (fast loading), to allow `bindmap` to remap the key-binds. The same effect has `zinit light -b ...`, i.e. additional `-b` option to the `light`-subcommand. **Does not work with snippets.**</div> |
| [**`wrap-track`**](https://zdharma-continuum.github.io/zinit/wiki/wrap-track) | <div align="justify" style='text-align: justify;'> Takes a `;`-separated list of function names that are to be investigated (meaning gathering report and unload data) **once** during execution. It works by wrapping the functions with a investigating-enabling and disabling snippet of code. In summary, `wrap-track` allows to extend the investigating 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.**</div> |
| `aliases` | <div align="justify" style="text-align: justify;">Load the plugin with the aliases mechanism enabled. Use with plugins that define **and use** aliases in their scripts.</div> |
| `light-mode` | <div align="justify" style="text-align: justify;">Load the plugin without the investigating, i.e.: as if it would be loaded with the `light` command. Useful for the for-syntax, where there is no `load` nor `light` subcommand</div> |
| [**`extract`**](https://zdharma-continuum.github.io/zinit/wiki/extract-Ice/) | <div align="justify" style="text-align: justify;">Performs archive extraction supporting multiple formats like `zip`, `tar.gz`, etc. and also notably OS X `dmg` images. If it has no value, then it works in the *auto* mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known **type** – the type is being read by the `file` Unix command. If not empty, then takes names of the files to extract. Refer to the Wiki page for further information.</div> |
| `subst` | <div align="justify" style="text-align: justify;">Substitute the given string into another string when sourcing the plugin script, e.g.: `zinit subst'autoload → autoload -Uz' …`.</div> |
| `autoload` | <div align="justify" style="text-align: justify;">Autoload the given functions (from their files). Equvalent to calling `atinit'autoload the-function'`. Supports renaming of the function – pass `'… → new-name'` or `'… -> new-name'`, e.g.: `zinit autoload'fun → my-fun; fun2 → my-fun2'`.</div> |
| `link` | <div align="justify" style="text-align: justify;">Use a symlink to cache a local snippet instead of copying into the snippets directory. Uses relative links if realpath >= 8.23 is found. ***Does not apply to URL-based snippets. Does not work with plugins.***</div> |
| 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. The third possible value is `as"null"` – a shorthand for `pick"/dev/null" nocompletions` – i.e.: it disables the default script-file sourcing and also the installation of completions. |
| `link` | Use a symlink to cache a local snippet instead of copying into the snippets directory. Uses relative links if realpath >= 8.23 is found. ***Does not apply to URL-based snippets. Does not work with plugins.*** |
| `id-as` | Nickname a plugin or snippet, to e.g. create a short handler for long-url snippet. |
| `subst` | Substitute the given string into another string when sourcing the plugin script, e.g.: `zinit subst'autoload → autoload -Uz' …`. |
| `aliases` | Load the plugin with the aliases mechanism enabled. Use with plugins that define **and use** aliases in their scripts. |
| `autoload` | Autoload the given functions (from their files). Equvalent to calling `atinit'autoload the-function'`. Supports renaming of the function – pass `'… → new-name'` or `'… -> new-name'`, e.g.: `zinit autoload'fun → my-fun; fun2 → my-fun2'`. |
| `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.** |
| `compile` | Pattern (+ possible `{...}` expansion, like `{a/*,b*}`) to select additional files to compile, e.g. \`compile"(pure\\ |
| `extract` | Performs archive extraction supporting multiple formats like `zip`, `tar.gz`, etc. and also notably OS X `dmg` images. If it has no value, then it works in the *auto* mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known **type** – the type is being read by the `file` Unix command. If not empty, then takes names of the files to extract. Refer to the Wiki page for further information. |
| `service` | Make following plugin or snippet a *service*, which will be ran in background, and only in single Zshell instance. See [the zservice-\* repositories](https://github.com/orgs/zdharma-continuum/repositories?q=zservice-). |
| `light-mode` | Load the plugin without the investigating, i.e.: as if it would be loaded with the `light` command. Useful for the for-syntax, where there is no `load` nor `light` subcommand |
| `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). |
| `trackbinds` | Shadow but only `bindkey` calls even with `zinit light ...`, i.e. even with investigating disabled (fast loading), to allow `bindmap` to remap the key-binds. The same effect has `zinit 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 investigated (meaning gathering report and unload data) **once** during execution. It works by wrapping the functions with a investigating-enabling and disabling snippet of code. In summary, `wrap-track` allows to extend the investigating 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.** |
| `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 `!`. |
### Order of Execution<a name="order-of-execution"></a>
@ -793,87 +795,88 @@ ## Zinit Commands<a name="zinit-commands"></a>
### Help<a name="help"></a>
| Command | Description |
| :----------------: | --------------------------------------------------------------------------- |
| `-h, --help, help` | <div align="justify" style="text-align: justify;"> Usage information.</div> |
| `man` | <div align="justify" style="text-align: justify;"> Manual.</div> |
| Command | Description |
| :-------- | --------------------- |
| `help` | Usage information. |
| `man` | Manual. |
| `version` | Display Zinit version |
### Loading and Unloading<a name="loading-and-unloading"></a>
| Command | Description |
| :----------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `load {plg-spec}` | <div align="justify" style="text-align: justify;"> Load plugin, can also receive absolute local path.</div> |
| `light [-b] {plg-spec}` | <div align="justify" style="text-align: justify;"> Light plugin load, without reporting/investigating. `-b` – investigate `bindkey`-calls only. There's also `light-mode` ice which can be used to induce the no-investigating (i.e.: *light*) loading, regardless of the command used.</div> |
| `unload [-q] {plg-spec}` | <div align="justify" style="text-align: justify;"> Unload plugin loaded with `zinit load ...`. `-q` – quiet.</div> |
| `snippet [-f] {url}` | <div align="justify" style="text-align: justify;"> Source local or remote file (by direct URL). `-f` – don't use cache (force redownload). The URL can use the following shorthands: `PZT::` (Prezto), `PZTM::` (Prezto module), `OMZ::` (Oh My Zsh), `OMZP::` (OMZ plugin), `OMZL::` (OMZ library), `OMZT::` (OMZ theme), e.g.: `PZTM::environment`, `OMZP::git`, etc.</div> |
| Command | Description |
| :----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `load {plg-spec}` | Load plugin, can also receive absolute local path. |
| `snippet [-f] {url}` | Source local or remote file (by direct URL). `-f` – don't use cache (force redownload). The URL can use the following shorthands: `PZT::` (Prezto), `PZTM::` (Prezto module), `OMZ::` (Oh My Zsh), `OMZP::` (OMZ plugin), `OMZL::` (OMZ library), `OMZT::` (OMZ theme), e.g.: `PZTM::environment`, `OMZP::git`, etc. |
| `light [-b] {plg-spec}` | Light plugin load, without reporting/investigating. `-b` – investigate `bindkey`-calls only. There's also `light-mode` ice which can be used to induce the no-investigating (i.e.: *light*) loading, regardless of the command used. |
| `unload [-q] {plg-spec}` | Unload plugin loaded with `zinit load ...`. `-q` – quiet. |
### Completions<a name="completions-1"></a>
| Command | Description |
| :-----------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code> clist \[*columns*\], completions \[*columns*\] </code> | <div align="justify" style="text-align: justify;"> List completions in use, with <code>*columns*</code> completions per line. `zpl clist 5` will for example print 5 completions per line. Default is 3.</div> |
| `cdisable {cname}` | <div align="justify" style="text-align: justify;"> Disable completion `cname`.</div> |
| `cenable {cname}` | <div align="justify" style="text-align: justify;"> Enable completion `cname`.</div> |
| `creinstall [-q] [-Q] {plg-spec}` | <div align="justify" style="text-align: justify;"> Install completions for plugin, can also receive absolute local path. `-q` – quiet. `-Q` - quiet all.</div> |
| `cuninstall {plg-spec}` | <div align="justify" style="text-align: justify;"> Uninstall completions for plugin.</div> |
| `csearch` | <div align="justify" style="text-align: justify;"> Search for available completions from any plugin.</div> |
| `compinit` | <div align="justify" style="text-align: justify;"> Refresh installed completions.</div> |
| `cclear` | <div align="justify" style="text-align: justify;"> Clear stray and improper completions.</div> |
| `cdlist` | <div align="justify" style="text-align: justify;"> Show compdef replay list.</div> |
| `cdreplay [-q]` | <div align="justify" style="text-align: justify;"> Replay compdefs (to be done after compinit). `-q` – quiet.</div> |
| `cdclear [-q]` | <div align="justify" style="text-align: justify;"> Clear compdef replay list. `-q` – quiet.</div> |
| Command | Description |
| :------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cclear` | Clear stray and improper completions. |
| `cdclear [-q]` | Clear compdef replay list. `-q` – quiet. |
| `cdisable {cname}` | Disable completion `cname`. |
| `cdlist` | Show compdef replay list. |
| `cdreplay [-q]` | Replay compdefs (to be done after compinit). `-q` – quiet. |
| `cenable {cname}` | Enable completion `cname`. |
| `clist \[*columns*\]`, `completions \[*columns*\]` | List completions in use, with <code>columns</code> completions per line. `zpl clist 5` will for example print 5 completions per line. Default is 3. |
| `compinit` | Refresh installed completions. |
| `creinstall [-q] [-Q] {plg-spec}` | Install completions for plugin, can also receive absolute local path. `-q` – quiet. `-Q` - quiet all. |
| `csearch` | Search for available completions from any plugin. |
| `cuninstall {plg-spec}` | Uninstall completions for plugin. |
### Tracking of the Active Session<a name="tracking-of-the-active-session"></a>
| Command | Description |
| :--------------: | ---------------------------------------------------------------------------------------------------------- |
| `dtrace, dstart` | <div align="justify" style="text-align: justify;"> Start investigating what's going on in session.</div> |
| `dstop` | <div align="justify" style="text-align: justify;"> Stop investigating what's going on in session.</div> |
| `dunload` | <div align="justify" style="text-align: justify;"> Revert changes recorded between dstart and dstop.</div> |
| `dreport` | <div align="justify" style="text-align: justify;"> Report what was going on in session.</div> |
| `dclear` | <div align="justify" style="text-align: justify;"> Clear report of what was going on in session.</div> |
| Command | Description |
| :--------------- | ------------------------------------------------- |
| `dclear` | Clear report of what was going on in session. |
| `dstop` | Stop investigating what's going on in session. |
| `dreport` | Report what was going on in session. |
| `dunload` | Revert changes recorded between dstart and dstop. |
| `dtrace, dstart` | Start investigating what's going on in session. |
### Reports and Statistics<a name="reports-and-statistics"></a>
| Command | Description |
| :--------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ` times [-s] [-m] [-a]` | <div align="justify" style="text-align: justify;"> Statistics on plugin load times, sorted in order of loading. `-s` – use seconds instead of milliseconds. `-m` – show plugin loading moments. `-a` - show both plugin load times and loading moments</div> |
| `zstatus` | <div align="justify" style="text-align: justify;"> Overall Zinit status.</div> |
| `report {plg-spec}\|--all` | <div align="justify" style="text-align: justify;"> Show plugin report. `--all` – do it for all plugins.</div> |
| `loaded [keyword], list [keyword]` | <div align="justify" style="text-align: justify;"> Show what plugins are loaded (filter with 'keyword').</div> |
| `ls` | <div align="justify" style="text-align: justify;"> List snippets in formatted and colorized manner. Requires **tree** program.</div> |
| `status {plg-spec}\|URL\|--all` | <div align="justify" style="text-align: justify;"> Git status for plugin or svn status for snippet. `--all` – do it for all plugins and snippets.</div> |
| `recently [time-spec]` | <div align="justify" style="text-align: justify;"> Show plugins that changed recently, argument is e.g. 1 month 2 days.</div> |
| `bindkeys` | <div align="justify" style="text-align: justify;"> Lists bindkeys set up by each plugin.</div> |
| Command | Description |
| :--------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ls` | List snippets in formatted and colorized manner. Requires `tree` program. |
| `bindkeys` | Lists bindkeys set up by each plugin. |
| `zstatus` | Overall Zinit status. |
| `report {plg-spec}` | Show plugin report. `--all` – do it for all plugins. |
| `status {plg-spec}` | 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. |
| `times [-s] [-m] [-a]` | Statistics on plugin load times, sorted in order of loading. `-s` – use seconds instead of milliseconds. `-m` – show plugin loading moments. `-a` - show both plugin load times and loading moments |
| `loaded [keyword], list [keyword]` | Show what plugins are loaded (filter with 'keyword'). |
### Compiling<a name="compiling"></a>
| Command | Description |
| :---------------------------: | ---------------------------------------------------------------------------------------------------------------------------- |
| `compile {plg-spec}\|--all` | <div align="justify" style="text-align: justify;"> Compile plugin. `--all` – compile all plugins.</div> |
| `uncompile {plg-spec}\|--all` | <div align="justify" style="text-align: justify;"> Remove compiled version of plugin. `--all` – do it for all plugins.</div> |
| `compiled` | <div align="justify" style="text-align: justify;"> List plugins that are compiled.</div> |
| Command | Description |
| :--------------------- | ------------------------------------------------------------------- |
| `compiled` | List plugins that are compiled. |
| `compile {plg-spec}` | Compile plugin. `--all` – compile all plugins. |
| `uncompile {plg-spec}` | Remove compiled version of plugin. `--all` – do it for all plugins. |
### Other<a name="other"></a>
| Command | Description |
| :--------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `self-update` | <div align="justify" style="text-align: justify;"> Updates and compiles Zinit.</div> |
| `update [-q] [-r] {plg-spec}\|URL\|--all` | <div align="justify" style="text-align: justify;"> Git update plugin or snippet.<br> `--all` – update all plugins and snippets.<br> `-q` – quiet.<br> `-r` \| `--reset` – run `git reset --hard` / `svn revert` before pulling changes.</div> |
| `ice <ice specification>` | <div align="justify" style="text-align: justify;"> Add ice to next command, argument is e.g. from"gitlab".</div> |
| `delete {plg-spec}\|URL\|--clean\|--all` | <div align="justify" style="text-align: justify;"> Remove plugin or snippet from disk (good to forget wrongly passed ice-mods). <br> `--all` – purge.<br> `--clean` – delete plugins and snippets that are not loaded.</div> |
| `cd {plg-spec}` | <div align="justify" style="text-align: justify;"> Cd into plugin's directory. Also support snippets if fed with URL.</div> |
| `edit {plg-spec}` | <div align="justify" style="text-align: justify;"> Edit plugin's file with $EDITOR.</div> |
| `glance {plg-spec}` | <div align="justify" style="text-align: justify;"> Look at plugin's source (pygmentize, {,source-}highlight).</div> |
| `stress {plg-spec}` | <div align="justify" style="text-align: justify;"> Test plugin for compatibility with set of options.</div> |
| `changes {plg-spec}` | <div align="justify" style="text-align: justify;"> View plugin's git log.</div> |
| `create {plg-spec}` | <div align="justify" style="text-align: justify;"> Create plugin (also together with GitHub repository).</div> |
| `srv {service-id} [cmd]` | <div align="justify" style="text-align: justify;"> Control a service, command can be: stop,start,restart,next,quit; `next` moves the service to another Zshell.</div> |
| `recall {plg-spec}\|URL` | <div align="justify" style="text-align: justify;"> Fetch saved ice modifiers and construct `zinit ice ...` command.</div> |
| `env-whitelist [-v] [-h] {env..}` | <div align="justify" style="text-align: justify;"> Allows to specify names (also patterns) of variables left unchanged during an unload. `-v` – verbose.</div> |
| `module` | <div align="justify" style="text-align: justify;"> Manage binary Zsh module shipped with Zinit, see `zinit module help`.</div> |
| `add-fpath\|fpath` `[-f\|--front]` `{plg-spec}` `[subdirectory]` | <div align="justify" style="text-align: justify;">Adds given plugin (not yet snippet) directory to `$fpath`. If the second argument is given, it is appended to the directory path. If the option `-f`/`--front` is given, the directory path is prepended instead of appended to `$fpath`. The `{plg-spec}` can be absolute path, i.e.: it's possible to also add regular directories.</div> |
| `run` `[-l]` `[plugin]` `{command}` | <div align="justify" style="text-align: justify;">Runs the given command in the given plugin's directory. If the option `-l` will be given then the plugin should be skipped – the option will cause the previous plugin to be reused.</div> |
| Command | Description |
| :--------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `module` | Manage binary Zsh module shipped with Zinit, see `zinit module help`. |
| `self-update` | Updates and compiles Zinit. |
| `cd {plg-spec}` | Cd into plugin's directory. Also support snippets if fed with URL. |
| `edit {plg-spec}` | Edit plugin's file with $EDITOR. |
| `changes {plg-spec}` | View plugin's git log. |
| `create {plg-spec}` | Create plugin (also together with GitHub repository). |
| `glance {plg-spec}` | Look at plugin's source (pygmentize, {,source-}highlight). |
| `stress {plg-spec}` | Test plugin for compatibility with set of options. |
| `recall {plg-spec}\|URL` | Fetch saved ice modifiers and construct `zinit ice ...` command. |
| `srv {service-id} [cmd]` | Control a service, command can be: stop,start,restart,next,quit; `next` moves the service to another Zshell. |
| `ice <ice specification>` | Add ice to next command, argument is e.g. from"gitlab". |
| `env-whitelist [-v] [-h] {env..}` | Allows to specify names (also patterns) of variables left unchanged during an unload. `-v` – verbose. |
| `run` `[-l]` `[plugin]` `{command}` | Runs the given command in the given plugin's directory. If the option `-l` will be given then the plugin should be skipped – the option will cause the previous plugin to be reused. |
| `delete {plg-spec}\|URL\|--clean\|--all` | Remove plugin or snippet from disk (good to forget wrongly passed ice-mods). <br> `--all` – purge.<br> `--clean` – delete plugins and snippets that are not loaded. |
| `update [-q] [-r] {plg-spec}\|URL\|--all` | Git update plugin or snippet.<br> `--all` – update all plugins and snippets.<br> `-q` – quiet.<br> `-r` \| `--reset` – run `git reset --hard` / `svn revert` before pulling changes. |
| `add-fpath\|fpath` `[-f\|--front]` `{plg-spec}` `[subdirectory]` | Adds given plugin (not yet snippet) directory to `$fpath`. If the second argument is given, it is appended to the directory path. If the option `-f`/`--front` is given, the directory path is prepended instead of appended to `$fpath`. The `{plg-spec}` can be absolute path, i.e.: it's possible to also add regular directories. |
## Updating Zinit and Plugins<a name="updating-zinit-and-plugins"></a>

4
_zinit
View file

@ -45,6 +45,7 @@ commands=(
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'
version:'display zinit version'
compile:'compile plugin (or all plugins if --all passed)'
uncompile:'remove compiled version of plugin (or of all plugins if --all passed)'
compiled:'show which plugins are compiled'
@ -74,6 +75,9 @@ case $state in
help)
_message "Hit enter to get usage information" && ret=0
;;
version)
_message "display zinit version" && ret=0
;;
man)
_message "Hit enter to view manual" && ret=0
;;

16
doc/HACKING.md
View file

@ -3,7 +3,7 @@ # Documentation
## README: Update the table of content
1. Install [doctoc](https://github.com/thlorenz/doctoc)
1. To update the TOC run the following command:
2. To update the TOC run the following command:
```zsh
doctoc --github README.md
@ -12,7 +12,7 @@ ## README: Update the table of content
## Update asciidoc and/or zshelldoc
1. Make sure you have [docker](https://www.docker.com/) or [podman](https://podman.io/) installed.
1. From the root of the repo, run:
2. From the root of the repo, run:
```zsh
make doc-container
@ -21,14 +21,14 @@ ## Update asciidoc and/or zshelldoc
If for some reason you want to build the zshelldocs or the PDF manually, you'll need:
1. Patience, zsd is very finicky about locales. You have been warned.
1. [zshelldoc (zsd)](https://github.com/zdharma-continuum/zshelldoc)
1. [asciidoc](https://asciidoc.org/)
1. `make doc`
2. [zshelldoc (zsd)](https://github.com/zdharma-continuum/zshelldoc)
3. [asciidoc](https://asciidoc.org/)
4. `make doc`
## Generate the manpage (doc/zinit.1)
1. Install [pandoc](https://pandoc.org/)
1. From the root of the repo run:
2. From the root of the repo run:
```zsh
pandoc --standalone --to man README.md -o doc/zinit.1
@ -44,8 +44,8 @@ ## Updating the gh-pages (zdharma-continuum.github.io)
```
2. Do your modifications and push your changes
1. Keep an eye on [the CI logs](https://github.com/zdharma-continuum/zinit/actions/workflows/gh-pages.yaml)
1. If all went well you can head to https://zdharma-continuum.github.io/ to see your changes live.
3. Keep an eye on [the CI logs](https://github.com/zdharma-continuum/zinit/actions/workflows/gh-pages.yaml)
4. If all went well you can head to https://zdharma-continuum.github.io/ to see your changes live.
**NOTE:** If you really **need** to push directly, without CI please refer to \[the README in the
documentation\]https://github.com/zdharma-continuum/zinit/blob/documentation/README.md

22
doc/zsdoc/zinit-autoload.zsh.adoc
View file

@ -76,6 +76,7 @@ FUNCTIONS
.zinit-update-or-status-all
.zinit-update-or-status-snippet
.zinit-wait-for-update-jobs
zi::version
DETAILS
-------
@ -774,7 +775,7 @@ ____
User-action entry point.
____
Has 66 line(s). Doesn't call other functions.
Has 67 line(s). Doesn't call other functions.
Called by:
@ -1407,3 +1408,22 @@ Called by:
.zinit-update-all-parallel
zi::version
~~~~~~~~~~~
____
Shows usage information.
User-action entry point.
____
Has 2 line(s). Calls functions:
zi::version
`-- zinit.zsh/+zinit-message
Called by:
zinit.zsh/zinit

8
doc/zsdoc/zinit.zsh.adoc
View file

@ -92,7 +92,7 @@ DETAILS
Script Body
~~~~~~~~~~~
Has 245 line(s). Calls functions:
Has 249 line(s). Calls functions:
Script-Body
|-- +zinit-message
@ -133,6 +133,7 @@ Has 245 line(s). Calls functions:
|   |-- zinit-autoload.zsh/.zinit-unload
|   |-- zinit-autoload.zsh/.zinit-update-or-status
|   |-- zinit-autoload.zsh/.zinit-update-or-status-all
|   |-- zinit-autoload.zsh/zi::version
|   |-- zinit-install.zsh/.zinit-compile-plugin
|   |-- zinit-install.zsh/.zinit-compinit
|   |-- zinit-install.zsh/.zinit-forget-completion
@ -191,6 +192,7 @@ Called by:
zinit-autoload.zsh/.zinit-update-or-status-all
zinit-autoload.zsh/.zinit-update-or-status
zinit-autoload.zsh/.zinit-wait-for-update-jobs
zinit-autoload.zsh/zi::version
zinit-install.zsh/.zinit-compile-plugin
zinit-install.zsh/.zinit-compinit
zinit-install.zsh/.zinit-download-file-stdout
@ -1284,7 +1286,7 @@ ____
and completion.
____
Has 560 line(s). Calls functions:
Has 564 line(s). Calls functions:
zinit
|-- +zinit-message
@ -1320,6 +1322,7 @@ Has 560 line(s). Calls functions:
|-- zinit-autoload.zsh/.zinit-unload
|-- zinit-autoload.zsh/.zinit-update-or-status
|-- zinit-autoload.zsh/.zinit-update-or-status-all
|-- zinit-autoload.zsh/zi::version
|-- zinit-install.zsh/.zinit-compile-plugin
|-- zinit-install.zsh/.zinit-compinit
|-- zinit-install.zsh/.zinit-forget-completion
@ -1409,6 +1412,7 @@ Has 1 line(s). Calls functions:
|-- zinit-autoload.zsh/.zinit-unload
|-- zinit-autoload.zsh/.zinit-update-or-status
|-- zinit-autoload.zsh/.zinit-update-or-status-all
|-- zinit-autoload.zsh/zi::version
|-- zinit-install.zsh/.zinit-compile-plugin
|-- zinit-install.zsh/.zinit-compinit
|-- zinit-install.zsh/.zinit-forget-completion

11
zinit-autoload.zsh
View file

@ -3352,9 +3352,15 @@ EOF
)
} # ]]]
# FUNCTION: zi::version [[[
# Shows usage information.
#
# Help function
#
# User-action entry point.
zi::version() {
+zinit-message "zinit{cmd} $(git --git-dir=$(realpath ${ZINIT[BIN_DIR]}/.git) describe --tags) {rst}(${OSTYPE}_${CPUTYPE})"
return $?
} # ]]]
# FUNCTION: .zinit-help [[[
# Shows usage information.
@ -3364,6 +3370,7 @@ EOF
builtin print -r -- "${ZINIT[col-p]}Usage${ZINIT[col-rst]}:
—— -h|--help|help – usage information
—— man – manual
—— version – display zinit version
—— self-update – updates and compiles Zinit
—— zstatus – overall Zinit statu—— times [-s] [-m] [-a] – statistics on plugin load times, sorted in order of loading; -s – use seconds instead of milliseconds, -m – show plugin loading moments, -a – show both load times and loading moments
—— load ${ZINIT[col-pname]}plg-spec${ZINIT[col-rst]} – load plugin, can also receive absolute local path

99
zinit.zsh
View file

@ -66,25 +66,63 @@ if [[ -z ${ZINIT[LIST_COMMAND]} ]]; then
fi
fi
ZINIT[ice-list]="svn|proto|from|teleid|bindmap|cloneopts|id-as|depth|if|wait|load|\
unload|blockf|pick|bpick|src|as|ver|silent|lucid|notify|mv|cp|\
atinit|atclone|atload|atpull|nocd|run-atpull|has|cloneonly|make|\
service|trackbinds|multisrc|compile|nocompile|completions|nocompletions|\
reset-prompt|wrap|reset|sh|\!sh|bash|\!bash|ksh|\!ksh|csh|\
\!csh|aliases|countdown|ps-on-unload|ps-on-update|trigger-load|\
light-mode|is-snippet|atdelete|pack|git|verbose|on-update-of|\
subscribe|extract|param|opts|autoload|subst|install|pullopts|\
debug|null|binary|link|configure"
ZINIT[nval-ice-list]="blockf|silent|lucid|trackbinds|cloneonly|nocd|run-atpull|\
nocompletions|sh|\!sh|bash|\!bash|ksh|\!ksh|csh|\!csh|\
aliases|countdown|light-mode|is-snippet|git|verbose|cloneopts|\
pullopts|debug|null|binary|make|nocompile|notify|reset"
ZINIT[cmds]="-h|--help|help|man|self-update|times|zstatus|load|light|unload|snippet|ls|ice|\
update|status|report|delete|loaded|list|cd|create|edit|glance|stress|changes|recently|clist|\
completions|cclear|cdisable|cenable|creinstall|cuninstall|csearch|compinit|dtrace|dstart|dstop|\
dunload|dreport|dclear|compile|uncompile|compiled|cdlist|cdreplay|cdclear|srv|recall|\
env-whitelist|bindkeys|module|add-fpath|fpath|run"
ZINIT[ice-list]="\
\!bash|\!csh|\!ksh|\!sh|\
aliases|as|atclone|atdelete|atinit|atload|atpull|autoload|\
bash|binary|bindmap|blockf|bpick|\
cloneonly|cloneopts|compile|completions|configure|countdown|cp|csh|\
debug|depth|\
extract|\
from|git|\
has|\
id-as|if|install|is-snippet|\
ksh|\
light-mode|link|load|lucid|\
make|multisrc|mv|nocd|nocompile|nocompletions|notify|null|\
on-update-of|opts|\
pack|param|pick|proto|ps-on-unload|ps-on-update|pullopts|\
reset|reset-prompt|run-atpull|\
service|sh|silent|src|subscribe|subst|svn|\
teleid|trackbinds|trigger-load|\
unload|\
ver|verbose|\
wait|wrap"
ZINIT[nval-ice-list]="\
\!bash|\!csh|\!ksh|\!sh|\
aliases|\
bash|binary|blockf|\
cloneonly|cloneopts|countdown|csh|\
debug|\
git|\
is-snippet|\
ksh|\
light-mode|lucid|\
make|\
nocd|nocompile|nocompletions|notify|null|\
pullopts|\
reset|run-atpull|\
sh|silent|\
trackbinds|\
verbose"
ZINIT[cmds]="\
-help|-h|\
add-fpath|\
bindkeys|\
cclear|cd|cdclear|cdisable|cdlist|cdreplay|cenable|changes|clist|compile|compiled|compinit|completions|create|creinstall|csearch|cuninstall|\
dclear|delete|dreport|dstart|dstop|dtrace|dunload|\
edit|env-whitelist|\
fpath|\
glance|\
help|\
ice|\
light|list|load|loaded|ls|\
man|module|\
recall|recently|report|run|\
self-update|snippet|srv|status|stress|\
times|\
uncompile|unload|update|\
version|\
zstatus"
# Can be customized.
: ${ZINIT[COMPLETIONS_DIR]:=${ZINIT[HOME_DIR]}/completions}
@ -2551,16 +2589,16 @@ zinit() {
--bindkeys opt_-b,--bindkeys
-x opt_-x,--command:"Load the snippet as a {cmd}command{rst}, i.e.: add it to {var}\$PATH{rst} and set {b-lhi}+x{rst} on it."
--command opt_-x,--command
env-whitelist "-h|--help|-v|--verbose"
update "-L|--plugins|-s|--snippets|-p|--parallel|-a|--all|\
-q|--quiet|-r|--reset|-u|--urge|-n|--no-pager|-v|--verbose|-h|--help"
delete "-a|--all|-c|--clean|-y|--yes|-q|--quiet|-h|--help"
unload "-h|--help|-q|--quiet"
cdclear "-h|--help|-q|--quiet"
cdreplay "-h|--help|-q|--quiet"
times "-h|--help|-m|-s"
light "-h|--help|-b"
snippet "-h|--help|-f|--force|--command|-x"
cdclear "--help|--quiet|-h|-q"
cdreplay "--help|--quiet|-h|-q"
delete "--all|--clean|--help|--quiet|--yes|-a|-c|-h|-q|-y"
env-whitelist "--help|--verbose|-h|-v"
light "--help|-b|-h"
snippet "--command|--force|--help|-f|-h|-x"
times "--help|-h|-m|-s"
unload "--help|--quiet|-h|-q"
update "--all|--help|--no-pager|--parallel|--plugins|--quiet|--reset|--snippets|--urge|--verbose|-L|-a|-h|-n|-p|-q|-r|-s|-u|-v"
version ""
)
cmd="$1"
@ -3065,6 +3103,9 @@ You can try to prepend {apo}${___q}{lhi}@{apo}'{error} to the ID if the last ice
(-h|--help|help)
.zinit-help
;;
(version)
zi::version
;;
(ls)
shift
.zinit-ls "$@"