{"id":20162547,"url":"https://github.com/zdharma-continuum/zsh-navigation-tools","last_synced_at":"2025-04-10T00:36:04.183Z","repository":{"id":46119534,"uuid":"423384117","full_name":"zdharma-continuum/zsh-navigation-tools","owner":"zdharma-continuum","description":"Curses-based tools for Zsh, e.g. multi-word history searcher","archived":false,"fork":false,"pushed_at":"2023-04-15T12:16:40.000Z","size":509,"stargazers_count":10,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T02:21:56.492Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://psprint.github.io/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zdharma-continuum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-11-01T08:05:10.000Z","updated_at":"2025-03-21T11:06:22.000Z","dependencies_parsed_at":"2024-01-07T13:11:03.841Z","dependency_job_id":null,"html_url":"https://github.com/zdharma-continuum/zsh-navigation-tools","commit_stats":null,"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-navigation-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-navigation-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-navigation-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzsh-navigation-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zdharma-continuum","download_url":"https://codeload.github.com/zdharma-continuum/zsh-navigation-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247749960,"owners_count":20989714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T00:25:39.156Z","updated_at":"2025-04-10T00:36:04.157Z","avatar_url":"https://github.com/zdharma-continuum.png","language":"Shell","funding_links":[],"categories":["Plugins"],"sub_categories":["ZSH on Windows"],"readme":"[![License (GPL version 3)](https://img.shields.io/badge/license-GNU%20GPL%20version%203-blue.svg?style=flat-square)](./LICENSE)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)\n![ZSH 5.0.0](https://img.shields.io/badge/zsh-v5.0.0-orange.svg?style=flat-square)\n[![Gitter][gitter-image]][gitter-link]\n\n![znt logo](http://imageshack.com/a/img905/2629/WK9qjN.png)\n\n# Zsh Navigation Tools\n\nAlso check out\n[![ZCA](http://imageshack.com/a/img911/8084/qSpO8a.png) Zsh Command Architect](https://github.com/zdharma-continuum/zsh-cmd-architect)\nand [Zconvey](https://github.com/zdharma-continuum/zconvey)\n\nVideos:\n\n- [https://youtu.be/QwZ8IJEgXRE](https://youtu.be/QwZ8IJEgXRE)\n- [https://youtu.be/DN9QqssAYB8](https://youtu.be/DN9QqssAYB8)\n\nScreenshots:\n\n![n-history](http://imageshack.com/a/img921/5046/bqr0mk.png)\n\n![n-history](http://imageshack.com/a/img633/9905/WzfSdl.gif)\n\nSet of tools like `n-history` – multi-word history searcher, `n-cd` – directory bookmark manager, `n-kill` – `htop` like\nkill utility, and more. Based on `n-list`, a tool generating selectable curses-based list of elements that has access to\ncurrent `Zsh` session, i.e. has broad capabilities to work together with it. Feature highlights include incremental\nmulti-word searching, approximate matching, ANSI coloring, themes, unique mode, horizontal scroll, grepping, advanced\nhistory management and various integrations with `Zsh`.\n\n## News\n\n- 06-10-2016\n\n  - **Tmux-integration** – `Ctrl-B H` in Tmux to open `n-history` in new window. Then select history entry, it will be\n    copied to the original Tmux window. Use this to execute local commands on remote hosts:\n\n    ![tmux integration](http://imageshack.com/a/img922/4760/oyX7eN.gif)\n\n    All that is needed is this line added to `~/.tmux.conf`:\n\n    ```\n    bind h run-shell -b \"$ZNT_REPO_DIR/doc/znt-tmux.zsh\"\n    ```\n\n    or – if Homebrew or other package manager is used:\n\n    ```\n    bind h run-shell -b \"$ZNT_REPO_DIR/znt-tmux.zsh\"\n    ```\n\n- 16-05-2016\n\n  - `n-kill` has completion. It proposes **words** from what's in `ps -A`. Giving `n-kill` arguments means grepping – it\n    will start only with matching `ps` entries.\n\n- 15-05-2016\n\n  - Fixed problem where zsh-syntax-highlighting could render `n-history` slow (for long history entries).\n\n- 14-05-2016\n\n  - Configuration can be set from `zshrc` (starting from `v2.1.12`). Documentation is [below](#configuration). Example:\n\n    ```zsh\n    znt_list_instant_select=1\n    znt_list_border=0\n    znt_list_bold=1\n    znt_list_colorpair=\"green/black\"\n    znt_functions_keywords=( \"zplg\" \"zgen\" \"match\" )\n    znt_cd_active_text=\"underline\"\n    znt_env_nlist_coloring_color=$'\\x1b[00;33m'\n    znt_cd_hotlist=( \"~/.config/znt\" \"/usr/share/zsh/site-functions\" \"/usr/share/zsh\"\n                     \"/usr/local/share/zsh/site-functions\" \"/usr/local/share/zsh\"\n                     \"/usr/local/bin\" )\n    ```\n\n- 10-05-2016\n\n  - Search query rotation – use `Ctrl-A` to rotate entered words right. Words `1 2 3` become `3 1 2`.\n\n- 09-05-2016\n\n  - New feature: n-help tool, available also from n-history via `H` key. It displays help screen with various\n    information on `ZNT`.\n\n    ![n-help](http://imageshack.com/a/img922/7595/MvtJdI.gif)\n\n- 08-05-2016\n\n  - Approximate matching – pressing `f` or `Ctrl-F` will enter \"`FIX`\" mode, in which `1` or `2` errors are allowed in\n    what's searched. This utilizes original Zsh approximate matching features and is intended to be used after entering\n    search query, when a typo is discovered.\n\n    ![fix mode](http://imageshack.com/a/img921/5756/64lFnv.gif)\n\n- 06-05-2016\n\n  - Private history can be edited. Use `e` key or `Ctrl-E` for that when in n-history. Your `$EDITOR` will start. This\n    is a way to have handy set of bookmarks prepared in private history's file.\n\n  - Border can be disabled. Use following snippet in `~/.config/znt/n-list.conf` or any other tool-targetted config\n    file:\n\n    ```zsh\n    # Should draw the border?\n    local border=0\n    ```\n\n- 30-04-2016\n\n  - New feature: color themes. Use `Ctrl-T` and `Ctrl-G` to browse predefined themes. They are listed in\n    [~/.config/znt/n-list.conf](https://github.com/zdharma-continuum/zsh-navigation-tools/blob/master/.config/znt/n-list.conf).\n    Use the file to permanently set a color scheme. Also, I sent a patch to Zsh developers and starting from Zsh \u003e 5.2\n    (not yet released) supported will be 256 colors. The file\n    [~/.config/znt/n-list.conf](https://github.com/zdharma-continuum/zsh-navigation-tools/blob/master/.config/znt/n-list.conf)\n    already has set of 256-color themes prepared :)\n\n    ![themes](http://imageshack.com/a/img924/4310/EbRh30.gif)\n\n- 29-04-2016\n\n  - New feature: private history – n-history tracks selected history entries, exposes them via new view (activated with\n    `F1`). It is shared across all sessions\n\n- 28-04-2016\n\n  - New features:\n    1. New n-history view (activated with `F1`): Most Frequent History Words\n    1. Predefined search keywords – use F2 to quickly search for chosen keywords (video:\n       [https://youtu.be/DN9QqssAYB8](https://youtu.be/DN9QqssAYB8))\n    1. Configuration option for doing instant selection in search mode\n\n## Installation\n\n```\nsh -c \"$(curl -fsSL https://raw.githubusercontent.com/zdharma-continuum/zsh-navigation-tools/master/doc/install.sh)\"\n```\n\nTo update run the command again.\n\n`ZNT` will be installed at `~/.config/znt/zsh-navigation-tools`, config files will be copied to `~/.config/znt`.\n`.zshrc` will be updated with only `8` lines of code, which will be added at the bottom.\n\nAfter installing and reloading shell give `ZNT` a quick try with `Ctrl-R` – this keyboard shortcut will open\n`n-history`.\n\n## Installation With [Zinit](https://github.com/zdharma-continuum/zinit)\n\nAdd `zinit load zdharma-continuum/zsh-navigation-tools` to `.zshrc`. The config files will be in `~/.config/znt`.\n\n## Installation With Zgenom/Zgen\n\nAdd `zgen load zdharma-continuum/zsh-navigation-tools` to `.zshrc` and issue a `zgen reset` (this assumes that there is\na proper `zgen save` construct in `.zshrc`). The config files will be available in `~/.config/znt`.\n\n## Installation With Antigen\n\nAdd `antigen bundle zdharma-continuum/zsh-navigation-tools` to `.zshrc`. There also should be `antigen apply`. The\nconfig files will be in `~/.config/znt`.\n\n## Single File Manual Installation\n\nRunning script `doc/generate_single_file` will create single-file version of `ZNT`. It can be sourced from `.zshrc`.\nDon't forget about configuration files as described above.\n\n## Manual Installation\n\nAfter extracting `ZNT` to `{some-directory}` add following two lines to `~/.zshrc`:\n\n```zsh\nfpath+=( {some-directory} )\nsource \"{some-directory}/zsh-navigation-tools.plugin.zsh\"\n```\n\nAs you can see, no plugin manager is needed to use the `*.plugin.zsh` file. The above two lines of code are all that\nalmost **all** plugin managers do. In fact, what's actually needed is only:\n\n```zsh\nsource \"{some-directory}/zsh-navigation-tools.plugin.zsh\"\n```\n\nbecause `ZNT` detects if it is used by **any** plugin manager and can handle `$fpath` update by itself.\n\n## Truly Manual Installation\n\nCopy (or link) all `n-*` and `znt-*` files to **/usr/share/zsh/site-functions/** (or\n**/usr/local/share/zsh/site-functions/**, check with `echo $fpath[1]`) and then add:\n\n```\nautoload n-list n-cd n-env n-kill n-panelize n-options n-aliases n-functions n-history n-help\n```\n\nto `~/.zshrc`.\n\nCreate aliases to avoid typing of the minus sign \"-\":\n\n```zsh\nalias naliases=n-aliases ncd=n-cd nenv=n-env nfunctions=n-functions nhistory=n-history\nalias nkill=n-kill noptions=n-options npanelize=n-panelize nhelp=n-help\n```\n\nDon't forget to copy\n[configuration files](https://github.com/zdharma-continuum/zsh-navigation-tools/tree/master/.config/znt). They should go\nto `~/.config/znt`. Moreover, `n-cd` works together with option `AUTO_PUSHD` and you should have:\n\n```zsh\nsetopt AUTO_PUSHD\n```\n\nin `.zshrc` (also recommend `PUSHD_IGNORE_DUPS`). Without the option `n-cd` will just work as incremental searcher of\ndirectory bookmarks.\n\n## History Widget\n\nTo have `n-history` as the incremental searcher bound to `Ctrl-R` copy `znt-*` files into the `*/site-functions` dir\n(unless you do single file install) and add:\n\n```zsh\nautoload znt-history-widget\nzle -N znt-history-widget\nbindkey \"^R\" znt-history-widget\n```\n\nto `.zshrc`. This is done automatically when using the installer, zgen, antigen or single file install. Two other\nwidgets exist, `znt-cd-widget` and `znt-kill-widget`, they too can be assigned to key combinations (`autoload` is done\nin `.zshrc` so no need of it):\n\n```zsh\nzle -N znt-cd-widget\nbindkey \"^B\" znt-cd-widget\nzle -N znt-kill-widget\nbindkey \"^Y\" znt-kill-widget\n```\n\n## Introduction\n\nThe tools are:\n\n- `n-aliases` - browses aliases, relegates editing to `vared`\n- `n-cd` - browses dirstack and bookmarked directories, allows to enter selected directory\n- `n-functions` - browses functions, relegates editing to `zed` or `vared`\n- `n-history` - browses history, allows to edit and run commands from it\n- `n-kill` - browses processes list, allows to send signal to selected process\n- `n-env` - browses environment, relegates editing to `vared`\n- `n-options` - browses options, allows to toggle their state\n- `n-panelize` - loads output of given command into the list for browsing\n\nAll tools support horizontal scroll with `\u003c`,`\u003e`, `{`,`}`, `h`,`l` or left and right cursors. Other keys are:\n\n- `H`, `?` (from n-history) - run n-help\n- `Ctrl-R` - start n-history, the incremental, multi-keyword history searcher (Zsh binding)\n- `Ctrl-A` - rotate entered words (1+2+3 -\u003e 3+1+2)\n- `Ctrl-F` - fix mode (approximate matching)\n- `Ctrl-L` - redraw of whole display\n- `Ctrl-T` - browse themes (next theme)\n- `Ctrl-G` - browse themes (previous theme)\n- `Ctrl-U` - half page up\n- `Ctrl-D` - half page down\n- `Ctrl-P` - previous element (also done with vim's k)\n- `Ctrl-N` - next element (also done with vim's j)\n- `[`, `]` - jump directory bookmarks in n-cd and typical signals in n-kill\n- `g`, `G` - beginning and end of the list\n- `/` - show incremental search\n- `F3` - show/hide incremental search\n- `Esc` - exit incremental search, clearing filter\n- `Ctrl-W` (in incremental search) - delete whole word\n- `Ctrl-K` (in incremental search) - delete whole line\n- `Ctrl-O`, `o` - enter uniq mode (no duplicate lines)\n- `Ctrl-E`, `e` - edit private history (when in private history view)\n- `F1` - (in n-history) - switch view\n- `F2`, `Ctrl-X`, `Ctrl-/` - search predefined keywords (defined in config files)\n\n## Configuration\n\n`ZNT` has configuration files located in `~/.config/znt`. The files are:\n\n```\nn-aliases.conf\nn-cd.conf\nn-env.conf\nn-functions.conf\nn-history.conf\nn-kill.conf\nn-list.conf\nn-options.conf\nn-panelize.conf\n```\n\n`n-list.conf` contains main configuration variables:\n\n```zsh\n# Should the list (text, borders) be drawn in bold\nlocal bold=0\n\n# Main color pair (foreground/background)\nlocal colorpair=\"white/black\"\n\n# Should draw the border?\nlocal border=1\n\n# Combinations of colors to try out with Ctrl-T and Ctrl-G\n# The last number is the bold option, 0 or 1\nlocal -a themes\nthemes=( \"white/black/1\" \"green/black/0\" \"green/black/1\" \"white/blue/0\" \"white/blue/1\"\n         \"magenta/black/0\" \"magenta/black/1\" )\n```\n\nRead remaining configuration files to see what's in them. Nevertheless, configuration can be also set from `zshrc`.\nThere are `5` standard `zshrc` configuration variables:\n\n```\nznt_history_active_text - underline or reverse - how should be active element highlighted\nznt_history_nlist_coloring_pattern - pattern that can be used to colorize elements\nznt_history_nlist_coloring_color - color with which to colorize\nznt_history_nlist_coloring_match_multiple - should multiple matches be colorized (0 or 1)\nznt_history_keywords (array) - search keywords activated with `Ctrl-X`, `F2` or `Ctrl-/`, e.g. ( \"git\" \"vim\" )\n```\n\nAbove variables will work for `n-history` tool. For other tools, change `_history_` to e.g. `_cd_`, for the `n-cd` tool.\nThe same works for all `8` tools.\n\nCommon configuration of the tools uses variables with `_list_` in them:\n\n```\nznt_list_bold - should draw text in bold (0 or 1)\nznt_list_colorpair - main pair of colors to be used, e.g \"green/black\"\nznt_list_border - should draw borders around windows (0 or 1)\nznt_list_themes (array) - list of themes to try out with Ctrl-T, e.g. ( \"white/black/1\" \"green/black/0\" )\nznt_list_instant_select - should pressing enter in search mode leave tool (0 or 1)\n```\n\nIf you used `ZNT` before `v2.1.12`, remove old configuration files `~/.config/znt/*.conf` so that `ZNT` can update them\nto the latest versions that support integration with `Zshrc`. If you used installer then run it again (after the remove\nof configuration files).\n\n## Programming\n\nThe function `n-list` is used as follows:\n\n```zsh\nn-list {element1} [element2] ... [elementN]\n```\n\nThis is all that is needed to be done to have the features like ANSI coloring, incremental multi-word search, unique\nmode, horizontal scroll, non-selectable elements (grepping is done outside `n-list`, see the tools for how it can be\ndone). To set up non-selectable entries add their indices into array `NLIST_NONSELECTABLE_ELEMENTS`:\n\n```zsh\ntypeset -a NLIST_NONSELECTABLE_ELEMENTS\nNLIST_NONSELECTABLE_ELEMENTS=( 1 )\n```\n\nResult is stored as `$reply[REPLY]` (`$` isn't needed before `REPLY` because of arithmetic context inside `[]`). The\nreturned array might be different from input arguments as `n-list` can process them via incremental search or uniq mode.\n`$REPLY` is the index in that possibly processed array. If `$REPLY` equals `-1` it means that no selection have been\nmade (user quitted via `q` key).\n\nTo set up entries that can be jumped to with `[`,`]` keys add their indices to `NLIST_HOP_INDEXES` array:\n\n```zsh\ntypeset -a NLIST_HOP_INDEXES\nNLIST_HOP_INDEXES=( 1 10 )\n```\n\n`n-list` can automatically colorize entries according to a `Zsh` pattern. Following example will colorize all numbers\nwith blue:\n\n```zsh\nlocal NLIST_COLORING_PATTERN=\"[0-9]##\"\nlocal NLIST_COLORING_COLOR=$'\\x1b[00;34m'\nlocal NLIST_COLORING_END_COLOR=$'\\x1b[0m'\nlocal NLIST_COLORING_MATCH_MULTIPLE=1\n\nn-list \"This is a number 123\" \"This line too has a number: 456\"\n```\n\nBlue is the default color, it doesn't have to be set. See `zshexpn` man page for more information on `Zsh` patterns.\nBriefly, comparing to regular expressions, `(#s)` is `^`, `(#e)` is `$`, `#` is `*`, `##` is `+`. Alternative will work\nwhen in parenthesis, i.e. `(a|b)`. BTW by using this method you can colorize output of the tools, via their config files\n(check out e.g. n-cd.conf, it is using this).\n\n## Performance\n\n`ZNT` are fastest with `Zsh` before `5.0.6` and starting from `5.2`\n\n## A tip\n\nZsh plugins may look scary, as they seem to have some \"architecture\". In fact, what a plugin really is, is that:\n\n1. It has its directory added to `fpath`\n1. It has any first `*.plugin.zsh` file sourced\n\nThat's it. When one contributes to Oh-My-Zsh or creates a plugin for any plugin manager, he only needs to account for\nthis. The same with doing any non-typical Zsh Navigation Tools installation.\n\n## More\n\n- be aware of\n  [this](https://github.com/zdharma-continuum/zsh-navigation-tools/blob/f49f910d239ae5bc6e1a5bb34930307b4f4e3ffe/zsh-navigation-tools.plugin.zsh#L35-L49)\n\n# Fixing tmux, screen and linux vt\n\nIf `TERM=screen-256color` (often a case for `tmux` and `screen` sessions) then `ncv` terminfo capability will have `2`nd\nbit set. This in general means that underline won't work. To fix this by creating your own `ncv=0`-equipped terminfo\nfile, run:\n\n```zsh\n{ infocmp -x screen-256color; printf '\\t%s\\n' 'ncv@,'; } \u003e /tmp/t \u0026\u0026 tic -x /tmp/t\n```\n\nA file will be created in directory `~/.terminfo` and will be automatically used, `tmux` and `screen` will work. Similar\nis for Linux virtual terminal:\n\n```zsh\n{ infocmp -x linux; printf '\\t%s\\n' 'ncv@,'; } \u003e /tmp/t \u0026\u0026 tic -x /tmp/t\n```\n\nIt will not display underline properly, but will instead highlight by a color, which is quite nice. The same will not\nwork for FreeBSD's vt, `ZNT` will detect if that vt is used and will revert to highlighting elements via `reverse` mode.\n\n[gitter-image]: https://badges.gitter.im/zdharma-continuum/community.svg\n[gitter-link]: https://gitter.im/zdharma-continuum/community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzsh-navigation-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzdharma-continuum%2Fzsh-navigation-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzsh-navigation-tools/lists"}