Documentation – share a useful trick with named directories.

README.md

@@ -1,3 +1,59 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Zinit<a name="zinit"></a>](#zinita-namezinita)
+  - [Zinit Wiki<a name="zinit-wiki"></a>](#zinit-wikia-namezinit-wikia)
+  - [Install<a name="install"></a>](#installa-nameinstalla)
+    - [Automatic<a name="automatic"></a>](#automatica-nameautomatica)
+    - [Manual<a name="manual"></a>](#manuala-namemanuala)
+  - [Usage<a name="usage"></a>](#usagea-nameusagea)
+    - [Introduction<a name="introduction"></a>](#introductiona-nameintroductiona)
+    - [Plugins and snippets<a name="plugins-and-snippets"></a>](#plugins-and-snippetsa-nameplugins-and-snippetsa)
+    - [Upgrade Zinit and plugins<a name="upgrade-zinit-and-plugins"></a>](#upgrade-zinit-and-pluginsa-nameupgrade-zinit-and-pluginsa)
+    - [Turbo and lucid<a name="turbo-and-lucid"></a>](#turbo-and-lucida-nameturbo-and-lucida)
+    - [Migration<a name="migration"></a>](#migrationa-namemigrationa)
+  - [Frequently Asked Questions<a name="frequently-asked-questions"></a>](#frequently-asked-questionsa-namefrequently-asked-questionsa)
+    - [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>](#use-zi-ice-svn-if-a-pluginsnippet-requires-an-entire-subdirectorya-nameuse-zi-ice-svn-if-a-pluginsnippet-requires-an-entire-subdirectorya)
+    - [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>](#use-zi-ice-ascompletion-to-directly-add-single-file-completion-snippetsa-nameuse-zi-ice-ascompletion-to-directly-add-single-file-completion-snippetsa)
+    - [More Examples<a name="more-examples"></a>](#more-examplesa-namemore-examplesa)
+- [How to Use<a name="how-to-use"></a>](#how-to-usea-namehow-to-usea)
+  - [Ice Modifiers<a name="ice-modifiers"></a>](#ice-modifiersa-nameice-modifiersa)
+    - [Cloning Options<a name="cloning-options"></a>](#cloning-optionsa-namecloning-optionsa)
+    - [Selection of Files (To Source, …)<a name="selection-of-files-to-source-%E2%80%A6"></a>](#selection-of-files-to-source-a-nameselection-of-files-to-source-a)
+    - [Conditional Loading<a name="conditional-loading"></a>](#conditional-loadinga-nameconditional-loadinga)
+    - [Plugin Output<a name="plugin-output"></a>](#plugin-outputa-nameplugin-outputa)
+    - [Completions<a name="completions"></a>](#completionsa-namecompletionsa)
+    - [Command Execution After Cloning, Updating or Loading<a name="command-execution-after-cloning-updating-or-loading"></a>](#command-execution-after-cloning-updating-or-loadinga-namecommand-execution-after-cloning-updating-or-loadinga)
+    - [Sticky-Emulation Of Other Shells<a name="sticky-emulation-of-other-shells"></a>](#sticky-emulation-of-other-shellsa-namesticky-emulation-of-other-shellsa)
+    - [Others<a name="others"></a>](#othersa-nameothersa)
+    - [Order of Execution<a name="order-of-execution"></a>](#order-of-executiona-nameorder-of-executiona)
+  - [Zinit Commands<a name="zinit-commands"></a>](#zinit-commandsa-namezinit-commandsa)
+    - [Help<a name="help"></a>](#helpa-namehelpa)
+    - [Loading and Unloading<a name="loading-and-unloading"></a>](#loading-and-unloadinga-nameloading-and-unloadinga)
+    - [Completions<a name="completions-1"></a>](#completionsa-namecompletions-1a)
+    - [Tracking of the Active Session<a name="tracking-of-the-active-session"></a>](#tracking-of-the-active-sessiona-nametracking-of-the-active-sessiona)
+    - [Reports and Statistics<a name="reports-and-statistics"></a>](#reports-and-statisticsa-namereports-and-statisticsa)
+    - [Compiling<a name="compiling"></a>](#compilinga-namecompilinga)
+    - [Other<a name="other"></a>](#othera-nameothera)
+  - [Updating Zinit and Plugins<a name="updating-zinit-and-plugins"></a>](#updating-zinit-and-pluginsa-nameupdating-zinit-and-pluginsa)
+  - [Completions<a name="completions-2"></a>](#completionsa-namecompletions-2a)
+    - [Calling `compinit` Without Turbo Mode<a name="calling-compinit-without-turbo-mode"></a>](#calling-compinit-without-turbo-modea-namecalling-compinit-without-turbo-modea)
+    - [Calling `compinit` With Turbo Mode<a name="calling-compinit-with-turbo-mode"></a>](#calling-compinit-with-turbo-modea-namecalling-compinit-with-turbo-modea)
+    - [Ignoring Compdefs<a name="ignoring-compdefs"></a>](#ignoring-compdefsa-nameignoring-compdefsa)
+    - [Disabling System-Wide `compinit` Call (Ubuntu)<a name="disabling-system-wide-compinit-call-ubuntu"></a>](#disabling-system-wide-compinit-call-ubuntua-namedisabling-system-wide-compinit-call-ubuntua)
+  - [Zinit Module<a name="zinit-module"></a>](#zinit-modulea-namezinit-modulea)
+  - [Hints and Tips<a name="hints-and-tips"></a>](#hints-and-tipsa-namehints-and-tipsa)
+    - [Customizing Paths<a name="customizing-paths"></a>](#customizing-pathsa-namecustomizing-pathsa)
+    - [Non-GitHub (Local) Plugins<a name="non-github-local-plugins"></a>](#non-github-local-pluginsa-namenon-github-local-pluginsa)
+    - [Extending Git<a name="extending-git"></a>](#extending-gita-nameextending-gita)
+    - [Use named directories for plugin dirs](#use-named-directories-for-plugin-dirs)
+  - [Changelog<a name="changelog"></a>](#changeloga-namechangeloga)
+  - [Support<a name="support"></a>](#supporta-namesupporta)
+  - [Getting Help and Community<a name="getting-help-and-community"></a>](#getting-help-and-communitya-namegetting-help-and-communitya)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 <p align="center">
   <a href="https://github.com/zdharma-continuum/zinit">
     <img src="https://raw.githubusercontent.com/zdharma-continuum/zinit/images/zinit.png"/>
@@ -675,6 +731,35 @@ Also, two articles on the Wiki present an example setup
 [here](https://zdharma-continuum.github.io/zinit/wiki/Example-Oh-My-Zsh-setup/).
 
 # How to Use<a name="how-to-use"></a>
+## Special variable-like strings `%NAME%`
+
+You can use a set of special var-like strings in any of the ices (currently: `atinit`, `atload`, `atclone`, `atpull`, `mv`, `cp`, `make`, `configure`, and a few others):
+
+- %ID%          – id-as ice
+- %USER%        – username (in user/plugin ID)
+- %PLUGIN%      – plugin name (in user/plugin ID)
+- %URL%         – snippet url
+- %DIR%         – plugin directory path 
+- %ZPFX%        – value of $ZPFX
+- %OS%          – `$OSTYPE`
+- %MACH%        – `$MACHTYPE`
+- %CPU%         – `$CPUTYPE`
+- %VENDOR%      – `$VENDOR`
+- %HOST%        – `$HOST`
+- %UID%         – `$UID` (numerical user id)
+- %GID%         – `$GID` (group #)
+
+For example:
+
+```zsh
+zinit id-as'plugin-%UID%' atload'print Loaded from dir: %DIR%, plugin id: %ID%' for zdharma-continuum/null
+```
+
+output is:
+
+```
+Loaded from dir: /home/q/.local/share/zinit/plugins/plugin-500, plugin id: plugin-500
+```
 
 ## Ice Modifiers<a name="ice-modifiers"></a>
 
@@ -1081,6 +1166,47 @@ zi as'null' lucid sbin wait'1' for \
 
 Target directory for installed files is `$ZPFX` (`~/.local/share/zinit/polaris` by default).
 
+### Use named directories for plugin dirs
+
+Named directories are shorthands in the form of `~NAMED_DIR`
+(upper case not required). They are setup via `hash` command
+with `-d` option, and point to a directory, for example:
+
+```zsh
+# Set up a GHUB named directory
+hash -d GHUB=~/github
+# Then use as:
+cd ~GHUB/my-project
+# PWD is now: ~/github/my-project
+```
+
+A nice usecase for it can be labelling all plugin directories
+with `~plugin-id` (for `user-id/plugin-id` plugin), via
+following snippet added to the end of zshrc:
+
+```zsh
+for i in $ZINIT[PLUGINS_DIR]/*; do
+    # Remove all except the final ID component.
+    q=${${i:t}##*---}
+    # Remove trailing slash.
+    q=${q%/}
+    # Hash the final ID part with directory.
+    # After this it's possible to `cd ~fzf`
+    # to get to directory of `junegunn/fzf`.
+    hash -d $q=$i
+done
+```
+## Changelog<a name="changelog"></a>
+
+Link to the [CHANGELOG](doc/CHANGELOG.md).
+## Completion for Plugin IDs and Ices
+
+Zinit supports a custom completion for plugin IDs (`Alt-Shift-A`) and
+for ices (`Alt-Shift-C`). Just place the cursor after e.g.: `wa` and
+press `Alt-Shift-C` to have it completed to `wait`. The same with
+plugin IDs – `fzf` then `Alt-Shift-A` to have `junegunn/fzf` (if it's
+installed).
+
 ## Changelog<a name="changelog"></a>
 
 Link to the [CHANGELOG](doc/CHANGELOG.md).

doc/zsdoc/zinit-autoload.zsh.adoc

@@ -12,71 +12,69 @@ Documentation automatically generated with `zshelldoc'
 
 FUNCTIONS
 ---------
-
- .zinit-any-to-uspl2
- .zinit-at-eval
- .zinit-build-module
- .zinit-cd
- .zinit-cdisable
- .zinit-cenable
- .zinit-changes
- .zinit-check-comp-consistency
- .zinit-check-which-completions-are-enabled
- .zinit-check-which-completions-are-installed
- .zinit-clear-completions
- .zinit-clear-report-for
- .zinit-compile-uncompile-all
- .zinit-compiled
- .zinit-confirm
- .zinit-create
- .zinit-delete
- .zinit-diff-env-compute
- .zinit-diff-functions-compute
- .zinit-diff-options-compute
- .zinit-diff-parameter-compute
- .zinit-edit
- .zinit-exists-message
- .zinit-find-completions-of-plugin
- .zinit-format-env
- .zinit-format-functions
- .zinit-format-options
- .zinit-format-parameter
- .zinit-get-completion-owner
- .zinit-get-completion-owner-uspl2col
- .zinit-get-path
- .zinit-glance
- .zinit-help
- .zinit-list-bindkeys
- .zinit-list-compdef-replay
- .zinit-ls
- .zinit-module
- .zinit-pager
- .zinit-prepare-readlink
- .zinit-recall
- .zinit-recently
- .zinit-restore-extendedglob
- .zinit-run-delete-hooks
- .zinit-save-set-extendedglob
- .zinit-search-completions
- .zinit-self-update
- .zinit-show-all-reports
- .zinit-show-completions
- .zinit-show-debug-report
- .zinit-show-registered-plugins
- .zinit-show-report
- .zinit-show-times
- .zinit-show-zstatus
- .zinit-stress
- .zinit-uncompile-plugin
- .zinit-uninstall-completions
- .zinit-unload
- .zinit-unregister-plugin
- .zinit-update-all-parallel
- .zinit-update-or-status
- .zinit-update-or-status-all
- .zinit-update-or-status-snippet
- .zinit-wait-for-update-jobs
- zi::version
+ zi::any-to-uspl2
+ zi::at-eval
+ zi::build-module
+ zi::cd
+ zi::cdisable
+ zi::cenable
+ zi::changes
+ zi::check-comp-consistency
+ zi::check-which-completions-are-enabled
+ zi::check-which-completions-are-installed
+ zi::clear-completions
+ zi::clear-report-for
+ zi::compile-uncompile-all
+ zi::compiled
+ zi::confirm
+ zi::create
+ zi::delete
+ zi::diff-env-compute
+ zi::diff-functions-compute
+ zi::diff-options-compute
+ zi::diff-parameter-compute
+ zi::edit
+ zi::exists-message
+ zi::find-completions-of-plugin
+ zi::format-env
+ zi::format-functions
+ zi::format-options
+ zi::format-parameter
+ zi::get-completion-owner
+ zi::get-completion-owner-uspl2col
+ zi::get-path
+ zi::glance
+ zi::help
+ zi::list-bindkeys
+ zi::list-compdef-replay
+ zi::ls
+ zi::module
+ zi::pager
+ zi::prepare-readlink
+ zi::recall
+ zi::recently
+ zi::restore-extendedglob
+ zi::run-delete-hooks
+ zi::save-set-extendedglob
+ zi::search-completions
+ zi::self-update
+ zi::show-all-reports
+ zi::show-completions
+ zi::show-debug-report
+ zi::show-registered-plugins
+ zi::show-report
+ zi::show-times
+ zi::show-zstatus
+ zi::stress
+ zi::uncompile-plugin
+ zi::uninstall-completions
+ zi::unload
+ zi::unregister-plugin
+ zi::update-all-parallel
+ zi::update-or-status
+ zi::update-or-status-all
+ zi::update-or-status-snippet
+ zi::wait-for-update-jobs
 
 DETAILS
 -------

share/config.site

@@ -0,0 +1,3 @@
+# Add directories carrying libs and headers to appropriate vars
+CPPFLAGS="-I$ZPFX/include $CPPFLAGS"
+LDFLAGS="-L$ZPFX/lib $LDFLAGS"

share/themes/blue.zsh

@@ -0,0 +1,41 @@
+
+# -*- mode: sh; sh-indentation: 4; indent-tabs-mode: nil; sh-basic-offset: 4; -*-
+# Copyright (c) 2016-2020 Sebastian Gniazdowski and contributors.
+
+ZINIT+=(
+    col-pname   $'\e[1;38;5;27m' col-uname   $'\e[1;38;5;39m'     col-keyword $'\e[27m'
+    col-note    $'\e[38;5;69m'   col-error   $'\e[1;38;5;9m'       col-p       $'\e[38;5;81m'
+    col-info    $'\e[38;5;39m'   col-info2   $'\e[38;5;227m'       col-profile $'\e[38;5;69m'
+    col-uninst  $'\e[38;5;118m'  col-info3   $'\e[1m\e[38;5;227m'  col-slight  $'\e[38;5;230m'
+    col-failure $'\e[38;5;75m'   col-happy   $'\e[1m\e[38;5;39m'   col-annex   $'\e[38;5;33m'
+    col-id-as   $'\e[1;4;38;5;75m'    col-version $'\e[3;38;5;69m'
+    # The more recent, fresh ones:
+    col-pre  $'\e[38;5;27m'   col-msg   $'\e[0m'       col-msg2  $'\e[38;5;174m'
+    col-obj  $'\e[38;5;208m'  col-obj2  $'\e[38;5;69m' col-file  $'\e[3;38;5;41m'
+    col-dir  $'\e[3;38;5;75m' col-func $'\e[38;5;208m'
+    col-url  $'\e[38;5;75m'   col-meta  $'\e[38;5;69m' col-meta2 $'\e[38;5;39m'
+    col-data $'\e[38;5;33m'   col-data2 $'\e[38;5;117m'   col-hi    $'\e[1m\e[38;5;208m'
+    col-var  $'\e[38;5;81m'   col-glob  $'\e[1;38;5;118m' col-ehi   $'\e[1m\e[38;5;208m'
+    col-cmd  $'\e[38;5;39m'   col-ice   $'\e[38;5;39m'    col-nl    $'\n'
+    col-txt  $'\e[38;5;254m'  col-num  $'\e[3;38;5;155m'  col-term  $'\e[38;5;185m'
+    col-warn $'\e[38;5;208m'  col-ok    $'\e[38;5;220m'   col-time  $'\e[38;5;220m'
+    col-apo $'\e[1;38;5;45m'   col-aps $'\e[38;5;117m'
+    col-quo $'\e[1;38;5;33m'   col-quos    $'\e[1;38;5;204m'
+    col-bapo $'\e[1;38;5;208m' col-baps $'\e[1;38;5;39m'
+    col-faint $'\e[38;5;238m'  col-opt   $'\e[1;38;5;75m'   col-lhi   $'\e[38;5;117m'
+    col-flag  $'\e[1;3;38;5;69m' col-pkg $'\e[1;3;38;5;27m'
+    col-tab  $' \t ' col-msg3  $'\e[38;5;238m'  col-b-lhi $'\e[1m\e[38;5;75m'
+    col-bar  $'\e[38;5;39m'  col-th-bar $'\e[38;5;39m'
+    col-…    "${${${(M)LANG:#*UTF-8*}:+…}:-...}"  col-ndsh  "${${${(M)LANG:#*UTF-8*}:+–}:-}"
+    col-mdsh $'\e[1;38;5;220m'"${${${(M)LANG:#*UTF-8*}:+–}:--}"$'\e[0m'
+    col-mmdsh $'\e[1;38;5;220m'"${${${(M)LANG:#*UTF-8*}:+――}:--}"$'\e[0m'
+    col--…   "${${${(M)LANG:#*UTF-8*}:+⋯⋯}:-···}" col-lr    "${${${(M)LANG:#*UTF-8*}:+↔}:-"«-»"}"
+    col-↔    ${${${(M)LANG:#*UTF-8*}:+$'\e[38;5;39m↔\e[0m'}:-$'\e[38;5;39m«-»\e[0m'}
+    col-rst  $'\e[0m'  col-b      $'\e[1m'          col-nb     $'\e[22m'
+    col-u    $'\e[4m'  col-it     $'\e[3m'          col-st     $'\e[9m'
+    col-nu   $'\e[24m' col-nit    $'\e[23m'         col-nst    $'\e[29m'
+    col-bspc $'\b'     col-b-warn $'\e[1;38;5;214m' col-u-warn $'\e[4;38;5;214m'
+    col-bcmd $'\e[38;5;220m'
+ )
+
+# vim: ft=zsh sw=4 ts=4 et foldmarker=[[[,]]] foldmethod=marker

share/themes/default.zsh

@@ -0,0 +1,46 @@
+# -*- mode: sh; sh-indentation: 4; indent-tabs-mode: nil; sh-basic-offset: 4; -*-
+# Copyright (c) 2016-2020 Sebastian Gniazdowski and contributors.
+
+ZINIT+=(
+    # Old colors: 31m
+    col-pname   $'\e[1;4m\e[32m' col-uname   $'\e[1;4m\e[35m'     col-keyword $'\e[32m'
+    col-note    $'\e[38;5;148m'  col-error   $'\e[1;38;5;9m'     col-p       $'\e[38;5;81m'
+    col-info    $'\e[38;5;82m'   col-info2   $'\e[38;5;227m'      col-profile $'\e[38;5;148m'
+    col-uninst  $'\e[38;5;118m'  col-info3   $'\e[1m\e[38;5;227m' col-slight  $'\e[38;5;230m'
+    col-failure $'\e[38;5;204m'  col-happy   $'\e[1m\e[38;5;82m'  col-annex   $'\e[38;5;153m'
+    col-id-as   $'\e[4;38;5;220m' col-version $'\e[3;38;5;87m'
+    # The more recent, fresh ones:
+    col-pre  $'\e[38;5;135m'  col-msg   $'\e[0m'        col-msg2  $'\e[38;5;172m'
+    col-obj  $'\e[38;5;218m'  col-obj2  $'\e[38;5;118m' col-file  $'\e[3;38;5;117m'
+    col-dir  $'\e[3;38;5;153m' col-func $'\e[38;5;219m'
+    col-url  $'\e[38;5;75m'   col-meta  $'\e[38;5;57m'  col-meta2 $'\e[38;5;147m'
+    col-data $'\e[38;5;82m'   col-data2 $'\e[38;5;117m' col-hi    $'\e[1m\e[38;5;183m'
+    col-var  $'\e[38;5;81m'   col-glob  $'\e[38;5;227m' col-ehi   $'\e[1m\e[38;5;210m'
+    col-cmd  $'\e[38;5;82m'   col-ice   $'\e[38;5;39m'  col-nl    $'\n'
+    col-txt  $'\e[38;5;254m' col-num  $'\e[3;38;5;155m' col-term  $'\e[38;5;185m'
+    col-warn $'\e[38;5;208m' col-ok    $'\e[38;5;220m'  col-time  $'\e[38;5;220m'
+    col-apo $'\e[1;38;5;45m' col-aps $'\e[38;5;117m'
+    col-quo $'\e[1;38;5;33m' col-quos    $'\e[1;38;5;160m'
+    col-bapo $'\e[1;38;5;220m' col-baps $'\e[1;38;5;82m'
+    col-faint $'\e[38;5;238m'  col-opt   $'\e[38;5;219m' col-lhi   $'\e[38;5;81m'
+    col-flag  $'\e[1;3;38;5;79m' col-pkg $'\e[1;3;38;5;27m'
+    col-tab  $' \t '             col-msg3  $'\e[38;5;238m' col-b-lhi $'\e[1m\e[38;5;75m'
+    col-bar  $'\e[38;5;82m'      col-th-bar $'\e[38;5;82m'
+    col-…    "${${${(M)LANG:#*UTF-8*}:+…}:-...}"  col-ndsh  "${${${(M)LANG:#*UTF-8*}:+–}:-}"
+    col-mdsh $'\e[1;38;5;220m'"${${${(M)LANG:#*UTF-8*}:+–}:--}"$'\e[0m'
+    col-mmdsh $'\e[1;38;5;220m'"${${${(M)LANG:#*UTF-8*}:+――}:--}"$'\e[0m'
+    col--…   "${${${(M)LANG:#*UTF-8*}:+⋯⋯}:-···}" col-lr    "${${${(M)LANG:#*UTF-8*}:+↔}:-"«-»"}"
+    col-↔    ${${${(M)LANG:#*UTF-8*}:+$'\e[38;5;82m↔\e[0m'}:-$'\e[38;5;82m«-»\e[0m'}
+    col-rst  $'\e[0m'  col-b      $'\e[1m'          col-nb     $'\e[22m'
+    col-u    $'\e[4m'  col-it     $'\e[3m'          col-st     $'\e[9m'
+    col-nu   $'\e[24m' col-nit    $'\e[23m'         col-nst    $'\e[29m'
+    col-bspc $'\b'     col-b-warn $'\e[1;38;5;214m' col-u-warn $'\e[4;38;5;214m'
+    col-bcmd $'\e[38;5;220m'
+)
+if [[ ( ${+terminfo} -eq 1 && ${terminfo[colors]} -ge 256 ) || \
+   ( ${+termcap} -eq 1 && ${termcap[Co]} -ge 256 )
+]] {
+    ZINIT+=( col-pname $'\e[1;4m\e[38;5;39m' col-uname  $'\e[1;4m\e[38;5;207m' )
+}
+
+# vim: ft=zsh sw=4 ts=4 et foldmarker=[[[,]]] foldmethod=marker