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

432 lines
16 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[![License (GPL version 3)](https://img.shields.io/badge/license-GNU%20GPL%20version%203-blue.svg?style=flat-square)](./LICENSE)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)
![ZSH 5.0.0](https://img.shields.io/badge/zsh-v5.0.0-orange.svg?style=flat-square)
![znt logo](http://imageshack.com/a/img905/2629/WK9qjN.png)
[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=D6XDCHDSBDSDG)
# Zsh Navigation Tools
Also check out [![ZCA](http://imageshack.com/a/img911/8084/qSpO8a.png) Zsh Command Architect](https://github.com/psprint/zsh-cmd-architect)
and [Zconvey](https://github.com/psprint/zconvey)
Videos:
- [https://youtu.be/QwZ8IJEgXRE](https://youtu.be/QwZ8IJEgXRE)
- [https://youtu.be/DN9QqssAYB8](https://youtu.be/DN9QqssAYB8)
Screenshots:
![n-history](http://imageshack.com/a/img921/5046/bqr0mk.png)
![n-history](http://imageshack.com/a/img633/9905/WzfSdl.gif)
Set of tools like `n-history`  multi-word history searcher, `n-cd` directory
bookmark manager, `n-kill`  `htop` like kill utility, and more. Based on
`n-list`, a tool generating selectable curses-based list of elements that has
access to current `Zsh` session, i.e. has broad capabilities to work together
with it. Feature highlights include incremental multi-word searching, approximate
matching, ANSI coloring, themes, unique mode, horizontal scroll, grepping, advanced
history management and various integrations with `Zsh`.
## News
* 06-10-2016
- **Tmux-integration** `Ctrl-B H` in Tmux to open `n-history` in new window.
Then select history entry, it will be copied to the original Tmux window.
Use this to execute local commands on remote hosts:
![tmux integration](http://imageshack.com/a/img922/4760/oyX7eN.gif)
All that is needed is this line added to `~/.tmux.conf`:
```
bind h run-shell -b "$ZNT_REPO_DIR/doc/znt-tmux.zsh"
```
or  if Homebrew or other package manager is used:
```
bind h run-shell -b "$ZNT_REPO_DIR/znt-tmux.zsh"
```
* 16-05-2016
- `n-kill` has completion. It proposes **words** from what's in `ps -A`. Giving `n-kill`
arguments means grepping it will start only with matching `ps` entries.
* 15-05-2016
- Fixed problem where zsh-syntax-highlighting could render `n-history` slow (for
long history entries).
* 14-05-2016
- Configuration can be set from `zshrc` (starting from `v2.1.12`). Documentation is [below](#configuration). Example:
```zsh
znt_list_instant_select=1
znt_list_border=0
znt_list_bold=1
znt_list_colorpair="green/black"
znt_functions_keywords=( "zplg" "zgen" "match" )
znt_cd_active_text="underline"
znt_env_nlist_coloring_color=$'\x1b[00;33m'
znt_cd_hotlist=( "~/.config/znt" "/usr/share/zsh/site-functions" "/usr/share/zsh"
"/usr/local/share/zsh/site-functions" "/usr/local/share/zsh"
"/usr/local/bin" )
```
* 10-05-2016
- Search query rotation use `Ctrl-A` to rotate entered words right.
Words `1 2 3` become `3 1 2`.
* 09-05-2016
- New feature: n-help tool, available also from n-history via `H` key. It
displays help screen with various information on `ZNT`.
![n-help](http://imageshack.com/a/img922/7595/MvtJdI.gif)
* 08-05-2016
- Approximate matching pressing `f` or `Ctrl-F` will enter "`FIX`" mode,
in which `1` or `2` errors are allowed in what's searched. This utilizes
original Zsh approximate matching features and is intended to be used
after entering search query, when a typo is discovered.
![fix mode](http://imageshack.com/a/img921/5756/64lFnv.gif)
* 06-05-2016
- Private history can be edited. Use `e` key or `Ctrl-E` for that when in
n-history. Your `$EDITOR` will start. This is a way to have handy set of
bookmarks prepared in private history's file.
- Border can be disabled. Use following snippet in `~/.config/znt/n-list.conf`
or any other tool-targetted config file:
```zsh
# Should draw the border?
local border=0
```
* 30-04-2016
- New feature: color themes. Use `Ctrl-T` and `Ctrl-G` to browse predefined
themes. They are listed in [~/.config/znt/n-list.conf](https://github.com/psprint/zsh-navigation-tools/blob/master/.config/znt/n-list.conf).
Use the file to permanently set a color scheme. Also, I sent a patch to Zsh developers
and starting from Zsh > 5.2 (not yet released) supported will be 256 colors.
The file [~/.config/znt/n-list.conf](https://github.com/psprint/zsh-navigation-tools/blob/master/.config/znt/n-list.conf)
already has set of 256-color themes prepared :)
![themes](http://imageshack.com/a/img924/4310/EbRh30.gif)
* 29-04-2016
- New feature: private history n-history tracks selected history entries,
exposes them via new view (activated with `F1`). It is shared across all
sessions
* 28-04-2016
- New features:
1. New n-history view (activated with `F1`): Most Frequent History Words
2. Predefined search keywords  use F2 to quickly search for chosen
keywords (video: [https://youtu.be/DN9QqssAYB8](https://youtu.be/DN9QqssAYB8))
3. Configuration option for doing instant selection in search mode
## Installation
```
sh -c "$(curl -fsSL https://raw.githubusercontent.com/psprint/zsh-navigation-tools/master/doc/install.sh)"
```
To update run the command again.
`ZNT` will be installed at `~/.config/znt/zsh-navigation-tools`, config files will be copied to `~/.config/znt`. `.zshrc`
will be updated with only `8` lines of code, which will be added at the bottom.
After installing and reloading shell give `ZNT` a quick try with `Ctrl-R` this keyboard shortcut will open `n-history`.
## Installation With [Zplugin](https://github.com/psprint/zplugin)
Add `zplugin load psprint/zsh-navigation-tools` to `.zshrc`. The config files will be in `~/.config/znt`.
## Installation With Zgen
Add `zgen load psprint/zsh-navigation-tools` to `.zshrc` and issue a `zgen reset` (this assumes that there is a proper `zgen save` construct in `.zshrc`).
The config files will be available in `~/.config/znt`.
## Installation With Antigen
Add `antigen bundle psprint/zsh-navigation-tools` to `.zshrc`. There also
should be `antigen apply`. The config files will be in `~/.config/znt`.
## Single File Manual Installation
Running script `doc/generate_single_file` will create single-file version of `ZNT`.
It can be sourced from `.zshrc`. Don't forget about configuration files as described
above.
## Manual Installation
After extracting `ZNT` to `{some-directory}` add following two lines
to `~/.zshrc`:
```zsh
fpath+=( {some-directory} )
source "{some-directory}/zsh-navigation-tools.plugin.zsh"
```
As you can see, no plugin manager is needed to use the `*.plugin.zsh`
file. The above two lines of code are all that almost **all** plugin
managers do. In fact, what's actually needed is only:
```zsh
source "{some-directory}/zsh-navigation-tools.plugin.zsh"
```
because `ZNT` detects if it is used by **any** plugin manager and can
handle `$fpath` update by itself.
## Truly Manual Installation
Copy (or link) all `n-*` and `znt-*` files to **/usr/share/zsh/site-functions/**
(or **/usr/local/share/zsh/site-functions/**, check with `echo $fpath[1]`) and then add:
autoload n-list n-cd n-env n-kill n-panelize n-options n-aliases n-functions n-history n-help
to `~/.zshrc`.
Create aliases to avoid typing of the minus sign "-":
```zsh
alias naliases=n-aliases ncd=n-cd nenv=n-env nfunctions=n-functions nhistory=n-history
alias nkill=n-kill noptions=n-options npanelize=n-panelize nhelp=n-help
```
Don't forget to copy [configuration files](https://github.com/psprint/zsh-navigation-tools/tree/master/.config/znt). They should go to `~/.config/znt`. Moreover, `n-cd` works together with option `AUTO_PUSHD` and you should have:
```zsh
setopt AUTO_PUSHD
```
in `.zshrc` (also recommend `PUSHD_IGNORE_DUPS`). Without the option `n-cd`
will just work as incremental searcher of directory bookmarks.
## History Widget
To have `n-history` as the incremental searcher bound to `Ctrl-R` copy `znt-*`
files into the `*/site-functions` dir (unless you do single file install) and
add:
```zsh
autoload znt-history-widget
zle -N znt-history-widget
bindkey "^R" znt-history-widget
```
to `.zshrc`. This is done automatically when using the installer, zgen, antigen
or single file install. Two other widgets exist, `znt-cd-widget` and
`znt-kill-widget`, they too can be assigned to key combinations (`autoload` is done
in `.zshrc` so no need of it):
```zsh
zle -N znt-cd-widget
bindkey "^B" znt-cd-widget
zle -N znt-kill-widget
bindkey "^Y" znt-kill-widget
```
## Introduction
The tools are:
- `n-aliases` - browses aliases, relegates editing to `vared`
- `n-cd` - browses dirstack and bookmarked directories, allows to enter selected directory
- `n-functions` - browses functions, relegates editing to `zed` or `vared`
- `n-history` - browses history, allows to edit and run commands from it
- `n-kill` - browses processes list, allows to send signal to selected process
- `n-env` - browses environment, relegates editing to `vared`
- `n-options` - browses options, allows to toggle their state
- `n-panelize` - loads output of given command into the list for browsing
All tools support horizontal scroll with `<`,`>`, `{`,`}`, `h`,`l` or left and right cursors. Other keys are:
- `H`, `?` (from n-history) - run n-help
- `Ctrl-R` - start n-history, the incremental, multi-keyword history searcher (Zsh binding)
- `Ctrl-A` - rotate entered words (1+2+3 -> 3+1+2)
- `Ctrl-F` - fix mode (approximate matching)
- `Ctrl-L` - redraw of whole display
- `Ctrl-T` - browse themes (next theme)
- `Ctrl-G` - browse themes (previous theme)
- `Ctrl-U` - half page up
- `Ctrl-D` - half page down
- `Ctrl-P` - previous element (also done with vim's k)
- `Ctrl-N` - next element (also done with vim's j)
- `[`, `]` - jump directory bookmarks in n-cd and typical signals in n-kill
- `g`, `G` - beginning and end of the list
- `/` - show incremental search
- `F3` - show/hide incremental search
- `Esc` - exit incremental search, clearing filter
- `Ctrl-W` (in incremental search) - delete whole word
- `Ctrl-K` (in incremental search) - delete whole line
- `Ctrl-O`, `o` - enter uniq mode (no duplicate lines)
- `Ctrl-E`, `e` - edit private history (when in private history view)
- `F1` - (in n-history) - switch view
- `F2`, `Ctrl-X`, `Ctrl-/` - search predefined keywords (defined in config files)
## Configuration
`ZNT` has configuration files located in `~/.config/znt`. The files are:
```
n-aliases.conf
n-cd.conf
n-env.conf
n-functions.conf
n-history.conf
n-kill.conf
n-list.conf
n-options.conf
n-panelize.conf
```
`n-list.conf` contains main configuration variables:
```zsh
# Should the list (text, borders) be drawn in bold
local bold=0
# Main color pair (foreground/background)
local colorpair="white/black"
# Should draw the border?
local border=1
# Combinations of colors to try out with Ctrl-T and Ctrl-G
# The last number is the bold option, 0 or 1
local -a themes
themes=( "white/black/1" "green/black/0" "green/black/1" "white/blue/0" "white/blue/1"
"magenta/black/0" "magenta/black/1" )
```
Read remaining configuration files to see what's in them. Nevertheless, configuration
can be also set from `zshrc`. There are `5` standard `zshrc` configuration variables:
```
znt_history_active_text - underline or reverse - how should be active element highlighted
znt_history_nlist_coloring_pattern - pattern that can be used to colorize elements
znt_history_nlist_coloring_color - color with which to colorize
znt_history_nlist_coloring_match_multiple - should multiple matches be colorized (0 or 1)
znt_history_keywords (array) - search keywords activated with `Ctrl-X`, `F2` or `Ctrl-/`, e.g. ( "git" "vim" )
```
Above variables will work for `n-history` tool. For other tools, change `_history_` to
e.g. `_cd_`, for the `n-cd` tool. The same works for all `8` tools.
Common configuration of the tools uses variables with `_list_` in them:
```
znt_list_bold - should draw text in bold (0 or 1)
znt_list_colorpair - main pair of colors to be used, e.g "green/black"
znt_list_border - should draw borders around windows (0 or 1)
znt_list_themes (array) - list of themes to try out with Ctrl-T, e.g. ( "white/black/1" "green/black/0" )
znt_list_instant_select - should pressing enter in search mode leave tool (0 or 1)
```
If you used `ZNT` before `v2.1.12`, remove old configuration files `~/.config/znt/*.conf` so that `ZNT`
can update them to the latest versions that support integration with `Zshrc`. If you used installer
then run it again (after the remove of configuration files).
## Programming
The function `n-list` is used as follows:
```zsh
n-list {element1} [element2] ... [elementN]
```
This is all that is needed to be done to have the features like ANSI coloring,
incremental multi-word search, unique mode, horizontal scroll, non-selectable
elements (grepping is done outside `n-list`, see the tools for how it can be
done). To set up non-selectable entries add their indices into array
`NLIST_NONSELECTABLE_ELEMENTS`:
```zsh
typeset -a NLIST_NONSELECTABLE_ELEMENTS
NLIST_NONSELECTABLE_ELEMENTS=( 1 )
```
Result is stored as `$reply[REPLY]` (`$` isn't needed before `REPLY` because
of arithmetic context inside `[]`). The returned array might be different from
input arguments as `n-list` can process them via incremental search or uniq
mode. `$REPLY` is the index in that possibly processed array. If `$REPLY`
equals `-1` it means that no selection have been made (user quitted via `q`
key).
To set up entries that can be jumped to with `[`,`]` keys add their indices to
`NLIST_HOP_INDEXES` array:
```zsh
typeset -a NLIST_HOP_INDEXES
NLIST_HOP_INDEXES=( 1 10 )
```
`n-list` can automatically colorize entries according to a `Zsh` pattern.
Following example will colorize all numbers with blue:
```zsh
local NLIST_COLORING_PATTERN="[0-9]##"
local NLIST_COLORING_COLOR=$'\x1b[00;34m'
local NLIST_COLORING_END_COLOR=$'\x1b[0m'
local NLIST_COLORING_MATCH_MULTIPLE=1
n-list "This is a number 123" "This line too has a number: 456"
```
Blue is the default color, it doesn't have to be set. See `zshexpn` man page
for more information on `Zsh` patterns. Briefly, comparing to regular
expressions, `(#s)` is `^`, `(#e)` is `$`, `#` is `*`, `##` is `+`. Alternative
will work when in parenthesis, i.e. `(a|b)`. BTW by using this method you can
colorize output of the tools, via their config files (check out e.g. n-cd.conf,
it is using this).
## Performance
`ZNT` are fastest with `Zsh` before `5.0.6` and starting from `5.2`
## A tip
Zsh plugins may look scary, as they seem to have some "architecture". In fact, what a plugin really is, is that:
1. It has its directory added to `fpath`
2. It has any first `*.plugin.zsh` file sourced
That's it. When one contributes to Oh-My-Zsh or creates a plugin for any plugin manager, he only needs to account for this.
The same with doing any non-typical Zsh Navigation Tools installation.
## More
- be aware of [this](https://github.com/psprint/zsh-navigation-tools/blob/f49f910d239ae5bc6e1a5bb34930307b4f4e3ffe/zsh-navigation-tools.plugin.zsh#L35-L49)
## IRC Channel
Channel `#zplugin@freenode` is a support place for all author's projects. Connect to:
[chat.freenode.net:6697](ircs://chat.freenode.net:6697/%23zplugin) (SSL) or [chat.freenode.net:6667](irc://chat.freenode.net:6667/%23zplugin)
and join #zplugin.
Following is a quick access via Webchat [![IRC](https://kiwiirc.com/buttons/chat.freenode.net/zplugin.png)](https://kiwiirc.com/client/chat.freenode.net:+6697/#zplugin)
# Fixing tmux, screen and linux vt
If `TERM=screen-256color` (often a case for `tmux` and `screen` sessions) then
`ncv` terminfo capability will have `2`nd bit set. This in general means that
underline won't work. To fix this by creating your own `ncv=0`-equipped
terminfo file, run:
```zsh
{ infocmp -x screen-256color; printf '\t%s\n' 'ncv@,'; } > /tmp/t && tic -x /tmp/t
```
A file will be created in directory `~/.terminfo` and will be automatically
used, `tmux` and `screen` will work. Similar is for Linux virtual terminal:
```zsh
{ infocmp -x linux; printf '\t%s\n' 'ncv@,'; } > /tmp/t && tic -x /tmp/t
```
It will not display underline properly, but will instead highlight by a color,
which is quite nice. The same will not work for FreeBSD's vt, `ZNT` will detect
if that vt is used and will revert to highlighting elements via `reverse` mode.