stow/oh-my-zsh/.oh-my-zsh/plugins/zsh-navigation-tools/README.md

   1 [![License (GPL version 3)](https://img.shields.io/badge/license-GNU%20GPL%20version%203-blue.svg?style=flat-square)](./LICENSE)
   2 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)
   3 ![ZSH 5.0.0](https://img.shields.io/badge/zsh-v5.0.0-orange.svg?style=flat-square)
   4 [![Gitter][gitter-image]][gitter-link]
   5
   6 ![znt logo](https://imageshack.com/a/img905/2629/WK9qjN.png)
   7
   8 # Zsh Navigation Tools
   9
  10 Set of tools like `n-history` – multi-word history searcher, `n-cd` – directory
  11 bookmark manager, `n-kill` – `htop` like kill utility, and more. Based on
  12 `n-list`, a tool generating selectable curses-based list of elements that has
  13 access to current `Zsh` session, i.e. has broad capabilities to work together
  14 with it. Feature highlights include incremental multi-word searching, approximate
  15 matching, ANSI coloring, themes, unique mode, horizontal scroll, grepping, advanced
  16 history management and various integrations with `Zsh`.
  17
  18 To use it, add `zsh-navigation-tools` to the plugins array in your zshrc file:
  19
  20 ```zsh
  21 plugins=(... zsh-navigation-tools)
  22 ```
  23
  24 Also check out [![ZCA](https://imageshack.com/a/img911/8084/qSpO8a.png) Zsh Command Architect](https://github.com/zdharma-continuum/zsh-cmd-architect)
  25 and [Zconvey](https://github.com/zdharma-continuum/zconvey)
  26
  27
  28
  29 Videos:
  30 - [https://youtu.be/QwZ8IJEgXRE](https://youtu.be/QwZ8IJEgXRE)
  31 - [https://youtu.be/DN9QqssAYB8](https://youtu.be/DN9QqssAYB8)
  32
  33 Screenshots:
  34
  35 ![n-history](https://imageshack.com/a/img921/5046/bqr0mk.png)
  36
  37 ![n-history](https://imageshack.com/a/img633/9905/WzfSdl.gif)
  38
  39
  40 ## History Widget
  41
  42 To have `n-history` as the incremental searcher bound to `Ctrl-R` copy `znt-*`
  43 files into the `*/site-functions` dir (unless you do single file install) and
  44 add:
  45
  46 ```zsh
  47 autoload znt-history-widget
  48 zle -N znt-history-widget
  49 bindkey "^R" znt-history-widget
  50 ```
  51
  52 to `.zshrc`. This is done automatically when using the installer, zgen, antigen
  53 or single file install. Two other widgets exist, `znt-cd-widget` and
  54 `znt-kill-widget`, they too can be assigned to key combinations (`autoload` is done
  55 in `.zshrc` so no need of it):
  56
  57 ```zsh
  58 zle -N znt-cd-widget
  59 bindkey "^B" znt-cd-widget
  60 zle -N znt-kill-widget
  61 bindkey "^Y" znt-kill-widget
  62 ```
  63
  64 ## Introduction
  65
  66 The tools are:
  67
  68 - `n-aliases` - browses aliases, relegates editing to `vared`
  69 - `n-cd` - browses dirstack and bookmarked directories, allows to enter selected directory
  70 - `n-functions` - browses functions, relegates editing to `zed` or `vared`
  71 - `n-history` - browses history, allows to edit and run commands from it
  72 - `n-kill` - browses processes list, allows to send signal to selected process
  73 - `n-env` - browses environment, relegates editing to `vared`
  74 - `n-options` - browses options, allows to toggle their state
  75 - `n-panelize` - loads output of given command into the list for browsing
  76
  77 All tools support horizontal scroll with `<`,`>`, `{`,`}`, `h`,`l` or left and right cursors. Other keys are:
  78
  79 - `H`, `?` (from n-history) - run n-help
  80 - `Ctrl-R` - start n-history, the incremental, multi-keyword history searcher (Zsh binding)
  81 - `Ctrl-A` - rotate entered words (1+2+3 -> 3+1+2)
  82 - `Ctrl-F` - fix mode (approximate matching)
  83 - `Ctrl-L` - redraw of whole display
  84 - `Ctrl-T` - browse themes (next theme)
  85 - `Ctrl-G` - browse themes (previous theme)
  86 - `Ctrl-U` - half page up
  87 - `Ctrl-D` - half page down
  88 - `Ctrl-P` - previous element (also done with vim's k)
  89 - `Ctrl-N` - next element (also done with vim's j)
  90 - `[`, `]` - jump directory bookmarks in n-cd and typical signals in n-kill
  91 - `g`, `G` - beginning and end of the list
  92 - `/` - show incremental search
  93 - `F3` - show/hide incremental search
  94 - `Esc` - exit incremental search, clearing filter
  95 - `Ctrl-W` (in incremental search) - delete whole word
  96 - `Ctrl-K` (in incremental search) - delete whole line
  97 - `Ctrl-O`, `o` - enter uniq mode (no duplicate lines)
  98 - `Ctrl-E`, `e` - edit private history (when in private history view)
  99 - `F1` - (in n-history) - switch view
 100 - `F2`, `Ctrl-X`, `Ctrl-/` - search predefined keywords (defined in config files)
 101
 102 ## Configuration
 103
 104 `ZNT` has configuration files located in `~/.config/znt`. The files are:
 105
 106 ```
 107 n-aliases.conf
 108 n-cd.conf
 109 n-env.conf
 110 n-functions.conf
 111 n-history.conf
 112 n-kill.conf
 113 n-list.conf
 114 n-options.conf
 115 n-panelize.conf
 116 ```
 117
 118 `n-list.conf` contains main configuration variables:
 119
 120 ```zsh
 121 # Should the list (text, borders) be drawn in bold
 122 local bold=0
 123
 124 # Main color pair (foreground/background)
 125 local colorpair="white/black"
 126
 127 # Should draw the border?
 128 local border=1
 129
 130 # Combinations of colors to try out with Ctrl-T and Ctrl-G
 131 # The last number is the bold option, 0 or 1
 132 local -a themes
 133 themes=( "white/black/1" "green/black/0" "green/black/1" "white/blue/0" "white/blue/1"
 134          "magenta/black/0" "magenta/black/1" )
 135 ```
 136
 137 Read remaining configuration files to see what's in them. Nevertheless, configuration
 138 can be also set from `zshrc`. There are `5` standard `zshrc` configuration variables:
 139
 140 ```
 141 znt_history_active_text - underline or reverse - how should be active element highlighted
 142 znt_history_nlist_coloring_pattern - pattern that can be used to colorize elements
 143 znt_history_nlist_coloring_color - color with which to colorize
 144 znt_history_nlist_coloring_match_multiple - should multiple matches be colorized (0 or 1)
 145 znt_history_keywords (array) - search keywords activated with `Ctrl-X`, `F2` or `Ctrl-/`, e.g. ( "git" "vim" )
 146 ```
 147
 148 Above variables will work for `n-history` tool. For other tools, change `_history_` to
 149 e.g. `_cd_`, for the `n-cd` tool. The same works for all `8` tools.
 150
 151 Common configuration of the tools uses variables with `_list_` in them:
 152
 153 ```
 154 znt_list_bold - should draw text in bold (0 or 1)
 155 znt_list_colorpair - main pair of colors to be used, e.g "green/black"
 156 znt_list_border - should draw borders around windows (0 or 1)
 157 znt_list_themes (array) - list of themes to try out with Ctrl-T, e.g. ( "white/black/1" "green/black/0" )
 158 znt_list_instant_select - should pressing enter in search mode leave tool (0 or 1)
 159 ```
 160
 161 If you used `ZNT` before `v2.1.12`, remove old configuration files `~/.config/znt/*.conf` so that `ZNT`
 162 can update them to the latest versions that support integration with `Zshrc`. If you used installer
 163 then run it again (after the remove of configuration files).
 164
 165 ## Programming
 166
 167 The function `n-list` is used as follows:
 168
 169 ```zsh
 170 n-list {element1} [element2] ... [elementN]
 171 ```
 172
 173 This is all that is needed to be done to have the features like ANSI coloring,
 174 incremental multi-word search, unique mode, horizontal scroll, non-selectable
 175 elements (grepping is done outside `n-list`, see the tools for how it can be
 176 done). To set up non-selectable entries add their indices into array
 177 `NLIST_NONSELECTABLE_ELEMENTS`:
 178
 179 ```zsh
 180 typeset -a NLIST_NONSELECTABLE_ELEMENTS
 181 NLIST_NONSELECTABLE_ELEMENTS=( 1 )
 182 ```
 183
 184 Result is stored as `$reply[REPLY]` (`$` isn't needed before `REPLY` because
 185 of arithmetic context inside `[]`). The returned array might be different from
 186 input arguments as `n-list` can process them via incremental search or uniq
 187 mode. `$REPLY` is the index in that possibly processed array. If `$REPLY`
 188 equals `-1` it means that no selection have been made (user quitted via `q`
 189 key).
 190
 191 To set up entries that can be jumped to with `[`,`]` keys add their indices to
 192 `NLIST_HOP_INDEXES` array:
 193
 194 ```zsh
 195 typeset -a NLIST_HOP_INDEXES
 196 NLIST_HOP_INDEXES=( 1 10 )
 197 ```
 198
 199 `n-list` can automatically colorize entries according to a `Zsh` pattern.
 200 Following example will colorize all numbers with blue:
 201
 202 ```zsh
 203 local NLIST_COLORING_PATTERN="[0-9]##"
 204 local NLIST_COLORING_COLOR=$'\x1b[00;34m'
 205 local NLIST_COLORING_END_COLOR=$'\x1b[0m'
 206 local NLIST_COLORING_MATCH_MULTIPLE=1
 207
 208 n-list "This is a number 123" "This line too has a number: 456"
 209 ```
 210
 211 Blue is the default color, it doesn't have to be set. See `zshexpn` man page
 212 for more information on `Zsh` patterns. Briefly, comparing to regular
 213 expressions, `(#s)` is `^`, `(#e)` is `$`, `#` is `*`, `##` is `+`. Alternative
 214 will work when in parenthesis, i.e. `(a|b)`. BTW by using this method you can
 215 colorize output of the tools, via their config files (check out e.g. n-cd.conf,
 216 it is using this).
 217
 218 ## Performance
 219
 220 `ZNT` are fastest with `Zsh` before `5.0.6` and starting from `5.2`
 221
 222 ## A tip
 223
 224 Zsh plugins may look scary, as they seem to have some "architecture". In fact, what a plugin really is, is that:
 225
 226 1. It has its directory added to `fpath`
 227 2. It has any first `*.plugin.zsh` file sourced
 228
 229 That's it. When one contributes to Oh-My-Zsh or creates a plugin for any plugin manager, they only need to account for this.
 230 The same with doing any non-typical Zsh Navigation Tools installation.
 231
 232 ## More
 233
 234 - be aware of [this](https://github.com/zdharma-continuum/zsh-navigation-tools/blob/f49f910d239ae5bc6e1a5bb34930307b4f4e3ffe/zsh-navigation-tools.plugin.zsh#L35-L49)
 235
 236 # Fixing tmux, screen and linux vt
 237
 238 If `TERM=screen-256color` (often a case for `tmux` and `screen` sessions) then
 239 `ncv` terminfo capability will have `2`nd bit set.  This in general means that
 240 underline won't work. To fix this by creating your own `ncv=0`-equipped
 241 terminfo file, run:
 242
 243 ```zsh
 244 { infocmp -x screen-256color; printf '\t%s\n' 'ncv@,'; } > /tmp/t && tic -x /tmp/t
 245 ```
 246
 247 A file will be created in directory `~/.terminfo` and will be automatically
 248 used, `tmux` and `screen` will work. Similar is for Linux virtual terminal:
 249
 250 ```zsh
 251 { infocmp -x linux; printf '\t%s\n' 'ncv@,'; } > /tmp/t && tic -x /tmp/t
 252 ```
 253
 254 It will not display underline properly, but will instead highlight by a color,
 255 which is quite nice. The same will not work for FreeBSD's vt, `ZNT` will detect
 256 if that vt is used and will revert to highlighting elements via `reverse` mode.
 257
 258 [gitter-image]: https://badges.gitter.im/zdharma-continuum/community.svg
 259 [gitter-link]: https://gitter.im/zdharma-continuum/community