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

Fix tables in README
Some checks failed
Container images / build-containers-with-zsh (5.2.4) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.3.1) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.4.2) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.5.1) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.6.2) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.7.1) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.8) (push) Has been cancelled
Details
Container images / build-containers-with-zsh (5.9) (push) Has been cancelled
Details
Lint / Markdown Lint (push) Has been cancelled
Details
Container images / build-container-latest (push) Has been cancelled
Details
Documentation / zshelldoc (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, annexes) (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, commands) (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, compile) (push) Has been cancelled
Details
Lint / ZSH Lint (zsh-noexec) (push) Has been cancelled
Details
Lint / ZSH Lint (zsh-zcompile) (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, gh-r) (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, ices) (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, plugins) (push) Has been cancelled
Details
Unit Tests / zunit-tests (macos-latest, snippets) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, annexes) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, commands) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, compile) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, gh-r) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, ices) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, plugins) (push) Has been cancelled
Details
Unit Tests / zunit-tests (ubuntu-latest, snippets) (push) Has been cancelled
Details

Browse source 
- Revert "lint: fmt README.md (#694)" (#695)
- Switch to markdownlint
- Fix markdown linting issues
This commit is contained in:
Philipp Schmitt 2025-01-28 18:01:31 +01:00 committed by GitHub
parent f654c77ef1
commit b096d6ef53
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 260 additions and 287 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -10,14 +10,41 @@ on:
workflow_dispatch:
jobs:
lint:
name: Lint
mdlint:
name: Markdown Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: xt0rted/markdownlint-problem-matcher@v3
- run: npm install -g markdownlint-cli
# disabled checks:
# - MD013/line-length
# - MD033/no-inline-html
# - MD034/no-bare-urls
# - MD036/no-emphasis-as-heading
# - MD041/first-line-heading/first-line-h1
- run: |
markdownlint --version
# List files to lint
ls *.md **/*.md
markdownlint \
--ignore '**/CHANGELOG.md' \
--disable MD013 MD033 MD034 MD036 MD041 -- \
*.md **/*.md
zshlint:
name: ZSH Lint
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
task: [markdown, zsh-noexec, zsh-zcompile]
task: [zsh-noexec, zsh-zcompile]
steps:
- uses: actions/checkout@v4
@ -30,15 +57,10 @@ jobs:
run: |
sudo apt-get update
sudo apt-get install --yes zsh
pip install --user linkify-it-py mdformat mdformat-config mdformat-gfm mdformat-shfmt mdformat-tables mdformat-toc
- name: "run lint (${{ matrix.task }})"
run: |
case "${{ matrix.task }}" in
markdown)
find . -name '*.md' ! -name 'CHANGELOG.md' -type f -print0 \
| xargs -0 -n1 -P4 mdformat --check --wrap 120 --number
;;
zsh-noexec)
find . -name '*.zsh' -type f -print0 \
| xargs -0 -n1 -P4 zsh -n

379
README.md
View file

@ -1,6 +1,6 @@
<p align="center">
<a href="https://github.com/zdharma-continuum/zinit">
<img src="https://raw.githubusercontent.com/zdharma-continuum/zinit/images/zinit.png"/>
<img alt="zinit logo" src="https://raw.githubusercontent.com/zdharma-continuum/zinit/images/zinit.png"/>
</a>
</p>
@ -63,7 +63,7 @@ # Zinit<a name="zinit"></a>
<p align="center">
<a href="https://github.com/zdharma-continuum/pm-perf-test">
<img width="550px" src="https://raw.githubusercontent.com/zdharma-continuum/zinit/images/startup-times.png"/>
<img alt="startup times graph" width="550px" src="https://raw.githubusercontent.com/zdharma-continuum/zinit/images/startup-times.png"/>
</a>
</p>
@ -692,157 +692,99 @@ ## Ice Modifiers<a name="ice-modifiers"></a>
### Cloning Options<a name="cloning-options"></a>
| 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.** |
| 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 | | :--------- |
\------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| | `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. |
| 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 | | :--------------------------- |
\------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| | `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'`. |
| 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 | | :------- |
\-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| | `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. |
| 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` | 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}`. |
| 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 | | :----------- |
\-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| | `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. |
| 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` | 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. |
| 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` | 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\\|async).zsh"` for `sindresorhus/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 `!`. |
| 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'*.zsh'`. |
| `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>
@ -855,52 +797,59 @@ ## Zinit Commands<a name="zinit-commands"></a>
### Help<a name="help"></a>
| Command | Description | | :-------- | --------------------- | | `help` | Usage information. | | `man` | Manual. | |
`version` | Display Zinit version |
| 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}` | 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. |
| 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 | | --------------------------------- |
\---------------------------------------------------------------------------------------------------------------------------------------------------
| | `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`. | |
`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. |
| 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`. |
| `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 | | ---------------- | ------------------------------------------------- | | `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. |
| 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 | | ------------------------ |
\--------------------------------------------------------------------------------------------------------------------------------------------------------
| | `bindkeys` | Lists bindkeys set up by each plugin. | | `list-plugins [keyword]` | Show what plugins are loaded
(filter with 'keyword'). | | `list-snippets` | List snippets in formatted and colorized manner. Requires `tree` program.
| | `recently [time-spec]` | Show plugins that changed recently, argument is e.g. 1 month 2 days. | |
`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. | | `zstatus` | Display brief statistics
for your Zinit installation. | | `times [-a] [-m] [-s]` | Print load times for each plugin. `-s` – Times are printed in
seconds. `-m` – Show plugin loading moments. `-a` - Times and loading moments are printed. |
| Command | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bindkeys` | Lists bindkeys set up by each plugin. |
| `list-plugins [keyword]` | Show what plugins are loaded (filter with 'keyword'). |
| `list-snippets` | List snippets in formatted and colorized manner. Requires `tree` program. |
| `recently [time-spec]` | Show plugins that changed recently, argument is e.g. 1 month 2 days. |
| `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. |
| `zstatus` | Display brief statistics for your Zinit installation. |
| `times [-a] [-m] [-s]` | Print load times for each plugin. `-s` – Times are printed in seconds. `-m` – Show plugin loading moments. `-a` - Times and loading moments are printed. |
### Compiling<a name="compiling"></a>
@ -912,8 +861,11 @@ #### compile<a name="compile"></a>
zinit [options] compile PLUGIN
```
| Option | Description | | ------------- | ------------------------- | | `-a, --all` | Compile all plugins | |
`-h, --help` | Print usage | | `-q, --quiet` | Suppress the build output |
| Option | Description |
| ------------- | ------------------------- |
| `-a, --all` | Compile all plugins |
| `-h, --help` | Print usage |
| `-q, --quiet` | Suppress the build output |
#### compiled<a name="compiled"></a>
@ -931,32 +883,32 @@ #### uncompile<a name="uncompile"></a>
zinit [options] uncompile PLUGIN
```
| Option | Description | | ------------- | ----------------------------------------- | | `-a, --all` | Remove any
compiled files for all plugins | | `-h, --help` | Print usage | | `-q, --quiet` | Suppress the output |
| Option | Description |
| ------------- | ----------------------------------------- |
| `-a, --all` | Remove any compiled files for all plugins |
| `-h, --help` | Print usage |
| `-q, --quiet` | Suppress the output |
### Other<a name="other"></a>
| 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. |
| 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>
@ -966,7 +918,7 @@ ## Updating Zinit and Plugins<a name="updating-zinit-and-plugins"></a>
issue `zinit update NAME_OF_PLUGIN`. A list of commits will be shown:
<p align="center">
<img src="./doc/img/update.png" />
<img alt="screenshot displaying zinit update tj/git-extras and its output" src="./doc/img/update.png" />
</p>
Some plugins require performing an action each time they're updated. One way you can do this is by using the `atpull`
@ -1117,10 +1069,10 @@ ### Using ZPFX variable<a name="using-zpfx-variable"></a>
Typical use cases when working with `$ZPFX` are, e.g.:
```zsh
$ ls $ZPFX
$ cd $ZPFX
$ cd $ZPFX/bin # note: $ZPFX/bin is automatically prepended to $PATH
$ cd $ZPFX/share
ls $ZPFX
cd $ZPFX
cd $ZPFX/bin # note: $ZPFX/bin is automatically prepended to $PATH
cd $ZPFX/share
```
Before the `configure''` ice appeared one would use `$ZPFX` as follows:
@ -1141,7 +1093,7 @@ # (supported are: configure, cmake, scons and meson)
To set ZPFX, one should do (in `.zshrc` before loading `zinit`):
```zsh
$ export ZPFX=$HOME/my-software # or: ZPFX=$HOME/.local, etc.
export ZPFX=$HOME/my-software # or: ZPFX=$HOME/.local, etc.
```
We encourage people to install compiled software with use of `$ZPFX` and `configure''` and `make''` ices, to have a
@ -1157,23 +1109,20 @@ ### Customizing Paths<a name="customizing-paths"></a>
declare -A ZINIT # initial Zinit's hash definition, if configuring before loading Zinit, and then:
```
| Hash Field | Description | | ----------------------------------- |
\--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| | ZINIT[BIN_DIR] | Where Zinit code resides, e.g.: "~/.local/share/zinit/zinit.git" | | ZINIT[HOME_DIR] | Where Zinit
should create all working directories, e.g.: "~/.local/share/zinit" | | ZINIT[MAN_DIR] | Directory where plugins can
store their manpages (`atclone"cp -vf myplugin.1 $ZINIT[MAN_DIR]/man1"`). If overridden, this directory will not
necessarily be used by `man` (See #8). Default: `$ZPFX/man` | | ZINIT[PLUGINS_DIR] | Override single working directory –
for plugins, e.g. "/opt/zsh/zinit/plugins" | | ZINIT[COMPLETIONS_DIR] | As above, but for completion files, e.g.
"/opt/zsh/zinit/root_completions" | | ZINIT[SNIPPETS_DIR] | As above, but for snippets | | ZINIT[LIST_COMMAND] | Command
to use for displaying a directory tree (e.g., `ls --tree`, `tree`, etc.) | | ZINIT[ZCOMPDUMP_PATH] | Path to
`.zcompdump` file, with the file included (i.e. its name can be different) | | ZINIT[COMPINIT_OPTS] | Options for
`compinit` call (i.e. done by `zicompinit`), use to pass -C to speed up loading | | ZINIT[MUTE_WARNINGS] | If set to
`1`, then mutes some of the Zinit warnings, specifically the `plugin already registered` warning | |
ZINIT[OPTIMIZE_OUT_DISK_ACCESSES] | If set to `1`, then Zinit will skip checking if a Turbo-loaded object exists on the
disk. By default Zinit skips Turbo for non-existing objects (plugins or snippets) to install them before the first
prompt – without any delays, during the normal processing of `zshrc`. This option can give a performance gain of about
10 ms out of 150 ms (i.e.: Zsh will start up in 140 ms instead of 150 ms). | | ZINIT[NO_ALIASES] | If set to `1`, then
Zinit will not set aliases such as `zi` or `zini` |
| Hash Field | Description |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ZINIT\[BIN_DIR\] | Where Zinit code resides, e.g.: "~/.local/share/zinit/zinit.git" |
| ZINIT\[HOME_DIR\] | Where Zinit should create all working directories, e.g.: "~/.local/share/zinit" |
| ZINIT\[MAN_DIR\] | Directory where plugins can store their manpages (`atclone"cp -vf myplugin.1 $ZINIT[MAN_DIR]/man1"`). If overridden, this directory will not necessarily be used by `man` (See #8). Default: `$ZPFX/man` |
| ZINIT\[PLUGINS_DIR\] | Override single working directory – for plugins, e.g. "/opt/zsh/zinit/plugins" |
| ZINIT\[COMPLETIONS_DIR\] | As above, but for completion files, e.g. "/opt/zsh/zinit/root_completions" |
| ZINIT\[SNIPPETS_DIR\] | As above, but for snippets |
| ZINIT\[LIST_COMMAND\] | Command to use for displaying a directory tree (e.g., `ls --tree`, `tree`, etc.) |
| ZINIT\[ZCOMPDUMP_PATH\] | Path to `.zcompdump` file, with the file included (i.e. its name can be different) |
| ZINIT\[COMPINIT_OPTS\] | Options for `compinit` call (i.e. done by `zicompinit`), use to pass -C to speed up loading |
| ZINIT\[MUTE_WARNINGS\] | If set to `1`, then mutes some of the Zinit warnings, specifically the `plugin already registered` warning |
| ZINIT\[OPTIMIZE_OUT_DISK_ACCESSES\] | If set to `1`, then Zinit will skip checking if a Turbo-loaded object exists on the disk. By default Zinit skips Turbo for non-existing objects (plugins or snippets) to install them before the first prompt – without any delays, during the normal processing of `zshrc`. This option can give a performance gain of about 10 ms out of 150 ms (i.e.: Zsh will start up in 140 ms instead of 150 ms). |
| ZINIT\[NO_ALIASES\] | If set to `1`, then Zinit will not set aliases such as `zi` or `zini` |
There is also `$ZPFX`, set by default to `~/.local/share/zinit/polaris` – a directory where software with `Makefile`,
etc. can be pointed to, by e.g. `atclone'./configure --prefix=$ZPFX'`.
@ -1223,7 +1172,7 @@ ## Support<a name="support"></a>
Zinit is a personal, free-time project with no funding and a huge
[feature request backlog](https://github.com/zdharma-continuum/zinit/issues). If you love it, consider supporting its
development via GitHub Sponsors [pending]. Any help counts!
development via GitHub Sponsors \[pending\]. Any help counts!
## Getting Help and Community<a name="getting-help-and-community"></a>

130
doc/HACKING.md
View file

@ -1,22 +1,24 @@
# Documentation
# HACKING.md
## README: Update the table of content
## Documentation
### README: Update the table of content
1. Install [doctoc](https://github.com/thlorenz/doctoc)
2. To update the TOC run the following command:
```zsh
doctoc --github README.md
```
```zsh
doctoc --github README.md
```
## Update asciidoc and/or zshelldoc
### Update asciidoc and/or zshelldoc
1. Make sure you have [docker](https://www.docker.com/) or [podman](https://podman.io/) installed.
2. From the root of the repo, run:
```zsh
make doc-container
```
```zsh
make doc-container
```
If for some reason you want to build the zshelldocs or the PDF manually, you'll need:
@ -25,23 +27,23 @@ ## Update asciidoc and/or zshelldoc
3. [asciidoc](https://asciidoc.org/)
4. `make doc`
## Generate the manpage (doc/zinit.1)
### Generate the manpage (doc/zinit.1)
1. Install [pandoc](https://pandoc.org/)
2. From the root of the repo run:
```zsh
pandoc --standalone --to man README.md -o doc/zinit.1
```
```zsh
pandoc --standalone --to man README.md -o doc/zinit.1
```
## Updating the gh-pages (zdharma-continuum.github.io)
### Updating the gh-pages (zdharma-continuum.github.io)
1. Check out the [documentation branch](https://github.com/zdharma-continuum/zinit/tree/documentation)
```shell
git fetch origin documentation
git checkout documentation
```
```shell
git fetch origin documentation
git checkout documentation
```
2. Do your modifications and push your changes
3. Keep an eye on [the CI logs](https://github.com/zdharma-continuum/zinit/actions/workflows/gh-pages.yaml)
@ -50,77 +52,77 @@ ## Updating the gh-pages (zdharma-continuum.github.io)
**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
# Testing
## Testing
We run out tests with [zunit](https://zunit.xyz).
We run our tests with [zunit](https://zunit.xyz).
To add a new test case:
1. Install [zunit](https://zunit.xyz) and [revolver](https://github.com/molovo/revolver):
```zsh
zinit for \
as"program" \
atclone"ln -sfv revolver.zsh-completion _revolver" \
atpull"%atclone" \
pick"revolver" \
@molovo/revolver \
as"completion" \
atclone"./build.zsh; ln -sfv zunit.zsh-completion _zunit" \
atpull"%atclone" \
sbin"zunit" \
@zunit-zsh/zunit
```
```zsh
zinit for \
as"program" \
atclone"ln -sfv revolver.zsh-completion _revolver" \
atpull"%atclone" \
pick"revolver" \
@molovo/revolver \
as"completion" \
atclone"./build.zsh; ln -sfv zunit.zsh-completion _zunit" \
atpull"%atclone" \
sbin"zunit" \
@zunit-zsh/zunit
```
2. Create a new `.zunit` file in the `tests/` dir. Here's a template:
```zsh
#!/usr/bin/env zunit
```zsh
#!/usr/bin/env zunit
@setup {
load setup
setup
}
@setup {
load setup
setup
}
@teardown {
load teardown
teardown
}
@teardown {
load teardown
teardown
}
@test 'zinit-annex-bin-gem-node installation' {
# This spawns the official zinit container, and executesa single zinit command
# inside it
run ./scripts/docker-run.sh --wrap --debug --zunit \
zinit light as"null" for zdharma-continuum/null
@test 'zinit-annex-bin-gem-node installation' {
# This spawns the official zinit container, and executes a single zinit command
# inside it
run ./scripts/docker-run.sh --wrap --debug --zunit \
zinit light as"null" for zdharma-continuum/null
# Verify exit code of the command above
assert $state equals 0
assert "$output" contains "Downloading"
# Verify exit code of the command above
assert $state equals 0
assert "$output" contains "Downloading"
local artifact="${PLUGINS_DIR}/zdharma-continuum---null/readme.md"
# Check if we downloaded the file correctly and if it is readable
assert "$artifact" is_file
assert "$artifact" is_readable
}
```
local artifact="${PLUGINS_DIR}/zdharma-continuum---null/readme.md"
# Check if we downloaded the file correctly and if it is readable
assert "$artifact" is_file
assert "$artifact" is_readable
}
```
You should of course also check out the existing tests ;)
You should of course also check out the existing tests ;)
3. To run your new test:
```zsh
zunit --verbose tests/your_test.zunit
```
```zsh
zunit --verbose tests/your_test.zunit
```
## Debugging tests
### Debugging tests
If you ever need to inspect the `ZINIT[HOME_DIR]` dir, where zinit's internal data is stored you can do so by commenting
out the `@teardown` section in your test. Then you can re-run said test and head over to `${TMPDIR:-/tmp}/zunit-zinit`.
Good luck!
# Misc
## Misc
## Get the list of supported ices
### Get the list of supported ices
To get the list in a quick-and-dirty fashion you issue: