## File: README.md # navi [](https://github.com/denisidoro/navi/actions) An interactive cheatsheet tool for the command-line. [](https://asciinema.org/a/406461) **navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands. Suggested values for arguments are dynamically displayed in a list. ## Pros - it will spare you from knowing CLIs by heart - it will spare you from copy-pasting output from intermediate commands - it will make you type less - it will teach you new one-liners It uses [fzf](https://github.com/junegunn/fzf) or [skim](https://github.com/lotabout/skim) under the hood and it can be either used as a command or as a shell widget (_à la_ Ctrl-R). ## Table of contents - [Installation](#installation) - [Usage](#usage) - [Cheatsheet repositories](#cheatsheet-repositories) - [Cheatsheet syntax](#cheatsheet-syntax) - [Customization](#customization) - [More info](#more-info) ## Installation The recommended way to install **navi** is by running: ```sh brew install navi ``` > [!NOTE] > For more details on how to install Navi, see [docs/installation](docs/installation/README.md) **navi** can be installed with the following package managers: [](https://repology.org/project/navi/versions) ## Usage There are multiple ways to use **navi**: - by typing `navi` in the terminal - pros: you have access to all possible subcommands and flags - as a [shell widget](docs/widgets/README.md#installing-the-shell-widget) for the terminal - pros: the shell history is correctly populated (i.e. with the actual command you ran instead of `navi`) and you can edit the command as you wish before executing it - as a [Tmux widget](docs/widgets/howto/TMUX.md) - pros: you can use your cheatsheets in any command-line app even in SSH sessions - as [aliases](docs/cheatsheet/syntax/README.md#aliases) - as a [shell scripting tool](docs/usage/shell-scripting/README.md) In particular, check [these instructions](https://github.com/denisidoro/navi/issues/491) if you want to replicate what's shown in the demo above. ## Cheatsheet repositories Running **navi** for the first time will help you download and manage cheatsheets. By default, they are stored at `~/.local/share/navi/cheats/`. You can also: - [browse through featured cheatsheets](docs/usage/commands/repo/README.md#browsing-through-cheatsheet-repositories) - [import cheatsheets from git repositories](docs/cheatsheet/repositories/README.md#importing-cheatsheet-repositories) - [write your own cheatsheets](#cheatsheet-syntax) (and [share them](docs/cheatsheet/repositories/README.md#submitting-cheatsheets), if you want) - [use cheatsheets from other tools](docs/cheatsheet/README.md#using-cheatsheets-from-other-tools), such as [tldr](https://github.com/tldr-pages/tldr) and [cheat.sh](https://github.com/chubin/cheat.sh) - [auto-update repositories](docs/cheatsheet/repositories/README.md#auto-updating-repositories) - auto-export cheatsheets from your [TiddlyWiki](https://tiddlywiki.com/) notes using a [TiddlyWiki plugin](https://bimlas.github.io/tw5-navi-cheatsheet/) ## Cheatsheet syntax Cheatsheets are described in `.cheat` files that look like this: ```sh % git, code # Change branch git checkout $ branch: git branch | awk '{print $NF}' ``` The full syntax and examples can be found [here](docs/cheatsheet/syntax/README.md). ## Customization You can: - [setup your own config file](docs/configuration/README.md) - [set custom paths for your config file and cheat sheets](docs/configuration/README.md#paths-and-environment-variables) - [change colors](docs/configuration/README.md#changing-colors) - [resize columns](docs/configuration/README.md#resizing-columns) - [change how search is performed](docs/configuration/README.md#overriding-fzf-options) ## More info Please run the following command to read more about all possible options: ```sh navi --help ``` In addition, please check the [/docs](docs) folder or the website. --- ## File: docs/installation/README.md # Installation of navi This is a reference of all known methods to install navi. > [!CAUTION] > Navi, as of now, has only two official builds, the released binaries on GitHub > and the published package on brew. > > All the other packages are community-maintained. ## Using package managers ### Homebrew ```sh brew install navi ``` > [!NOTE] > See [brew.sh](https://brew.sh/) for more details. ### Using Gentoo > [!WARNING] > You need to enable the GURU overlay for the instructions below to work correctly. > > For more details see: > > - [wiki.gentoo.org/wiki/Ebuild_repository](https://wiki.gentoo.org/wiki/Ebuild_repository) > - [gpo.zugaina.org/Overlays/guru/app-misc/navi](https://gpo.zugaina.org/Overlays/guru/app-misc/navi). ```sh emerge -a app-misc/navi ``` > [!NOTE] > See [Gentoo.org](https://gentoo.org/) for more details. ### Using Pacman ```sh pacman -S navi ``` > [!NOTE] > See [wiki.archlinux.org/title/Pacman](https://wiki.archlinux.org/title/Pacman) for more details. ### Using nix ```sh nix-env -iA nixpkgs.navi ``` > [!NOTE] > See [nixos.org](https://nixos.org/) for more details ### Using Cargo ```bash cargo install --locked navi ``` > [!NOTE] > See [@rust-lang/cargo](https://github.com/rust-lang/cargo) for more details. ### Using Chocolatey ```bash choco install navi ``` > [!CAUTION] > You currently need to create the config file `$env:USERPROFILE\AppData\Roaming\navi\config.yaml` > and define the `shell.command` directive as `powershell` for navi to work correctly. > > ```yaml > shell: > command: powershell > ``` > [!NOTE] > See [community.chocolatey.org](https://community.chocolatey.org) for more details. ## Using the installation script Navi has an installation script ready for you to use, you can call it like this: ```bash bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install) ``` If you need to define the directory for the binary, you can call it like this: ```bash BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install) ``` ## Downloading pre-compiled binaries With each release, we try our best to build and publish a binary for each supported platform, you can find them here: [@denisidoro/navi/releases/latest](https://github.com/denisidoro/navi/releases/latest) What you need to do is: - to download the binary corresponding to the version you want to install - to extract the content of the archive to your `$PATH` ## Building from source You can also build navi from source, it's mainly used by contributors to test their modifications but can be used by end users who want to build their own version. - You need to clone the repository: ```bash git clone https://github.com/denisidoro/navi && cd navi ``` - Call `make` ```bash make install ``` You can specify the binary directory with: ```bash make BIN_DIR=/usr/local/bin install ``` ## Compile time environment variables **navi** supports environment variables at compile time that will modify the behavior of navi at runtime, they are: | Environment variable | Description | |----------------------|-------------------------------------------------------------| | `NAVI_PATH` | This defines the default path used by navi for cheatsheets. | | `NAVI_CONFIG` | This defines the default configuration file used by navi. | ## Other package managers You can find **navi** for more package managers by clicking on the image below: [](https://repology.org/project/navi/versions) Feel free to be the maintainer of **navi** for any package manager you'd like! --- ## File: docs/deprecated/Alfred/README.md # Alfred > [!CAUTION] > This feature has been deprecated and support has been dropped since 2.16.0. > > The latest version with support is [2.15.1](https://github.com/denisidoro/navi/releases/tag/v2.15.1). This is _experimental_. If you face any issues, please report [here](https://github.com/denisidoro/navi/issues/348). ### Instructions - make sure you have [Alfred Powerpack](https://www.alfredapp.com/powerpack/) - make sure **navi** [2.15.1](https://github.com/denisidoro/navi/releases/tag/v2.15.1) is installed - make sure that the `navi` binary is in the `$PATH` determined by `~/.bashrc` - download and install the [latest .alfredworkflow available](https://github.com/denisidoro/navi/releases/tag/v2.15.1) --- ## File: docs/contributions/documentation/README.md # Contribute documentation to Navi If you don't want or can't code in Rust, we welcome all contributions, even more so if it's related to documentation. The documentation of Navi is currently made in Markdown. ## Markdown documentation The documentation source files are located in the `docs/` folder and are mainly grouped by features. The current documentation follows a structure where one folder equals one topic. Here is a quick representation of the folder structure this documentation currently follows: ```txt . +-- docs | +-- examples | | +-- | +-- src | | +-- | | | +-- | +-- | | +-- README.md ``` You can see that we have separated the `src` and `examples` folder from the topic with the intent to make it easier to find each type of documentation. > [!NOTE] > It is recommended to not go deeper than 3 levels in the documentation. --- ## File: docs/contributions/code/README.md # Contribute code to Navi Navi is written in Rust, the widgets may be written in any language given it can be integrated with Navi. If you take the example of the most common widgets for Navi they are written in their shell scripting language because they intend to integrate Navi with the shell in question (Fish, Zsh, NuShell, PowerShell, etc.). We separate Navi into two categories: - `Navi Core` which refers to Navi's code in Rust - `Navi Widgets` which refers to code that intends to integrate Navi with a 3rd-party software ## Contribute to Navi Core If you want to contribute to Navi Core there are certain steps you need to follow for your changes to be accepted. 1. First, open an issue if no opened issues are related to the change you want to contribute. 2. [Optional] Wait to have an opinion from the maintainers, developers or contributors from Navi. > This step is marked as *Optional* as you can open a Merge Request (MR)/Pull Request (PR) > without having to open an issue beforehand, although it is recommended to not do so. We ask you to wait before working on a PR as the way you see a feature and its implementation might not be similar on how a maintainer of Navi sees it. This will save you and the maintainers time. 3. Fork the repository and iterate over your changes. 4. Update Navi documentation If you implement a new feature, you will need to create a new entry in the project's documentation for users to know what has changed. No significant modification in Navi's behaviour should be merged without being documented.\ For more details I recommend you to see [contributions/documentation/](../documentation/README.md). 5. Open a PR on [denisidoro/navi](https://github.com/denisidoro/navi/pulls) and request a review 6. [Optional] Your PR needs revisions and changes before it can be merged It's not rare that your PR will need changes before it can be accepted by the maintainers and then merged into the main branch. 7. Your PR has been merged Congratulations! Your PR has been reviewed and merged, you should be proud of it, and we thank you for your contribution. The next release cycle will package all contributions into a new release and users throughout the world will be able to use your new feature(s). --- ## File: docs/contributions/bugs/README.md # Contribute in opening bug tickets Like any other software, navi has bugs. If you encounter an issue with Navi, we encourage you to open a bug ticket.\ Please see [Bug report template](../../../.github/ISSUE_TEMPLATE/bug_report.md) then proceed to [Issues tab](https://github.com/denisidoro/navi/issues/) to open an issue. --- ## File: docs/contributions/README.md # Navi contributors This section is about the ways you can contribute to Navi and its ecosystem. * [Navi contributors](#navi-contributors) * [How to contribute to Navi](#how-to-contribute-to-navi) * [Versioning Scheme](#versioning-scheme) * [Deprecation of features](#deprecation-of-features) ## How to contribute to Navi You have multiple ways to contribute to navi, here are the documented ones: - [Write code for Navi](code/README.md) - [Write documentation for Navi](documentation/README.md) - [Open Bug tickets](bugs/README.md) Please see each section for more details. ## Versioning Scheme | Type | Description | |-------|--------------------------------------------------------------------------------------------------| | Major | Anything which introduces a major breaking change. The bash to rust rewrite was such an example. | | Minor | Almost everything. | | Fix | A fix, just like its name. It should be micro releases with minimal changes. | ## Deprecation of features Once you introduce a feature, you need to have a clear view of when we're going to remove its support within navi. In order to offer stability to the users, we prefer having 10 minor versions between the deprecation notice and the removal of its support. ````txt Version where the feature is being deprecated: 0.10.0 Version where the support is dropped: 0.20.0 ```` > [!NOTE] > This rule is not absolute and each feature deprecation needs to be handled > carefully given its own circumstances, but try to stick as close as possible > to this rule. --- ## File: docs/configuration/README.md # Configuring Navi Navi allows you to configure it with a YAML configuration. * [Configuring Navi](#configuring-navi) * [Paths and Environment Variables](#paths-and-environment-variables) * [The default configuration file path](#the-default-configuration-file-path) * [Cheatsheets paths](#cheatsheets-paths) * [The default cheatsheets path](#the-default-cheatsheets-path) * [Defining the cheatsheets path with the environment variable](#defining-the-cheatsheets-path-with-the-environment-variable) * [Defining the cheatsheets path in the configuration file](#defining-the-cheatsheets-path-in-the-configuration-file) * [[DEPRECATED] - Using the `path` directive](#deprecated---using-the-path-directive) * [Customization](#customization) * [Changing colors](#changing-colors) * [fzf color scheme](#fzf-color-scheme) * [Navi colors](#navi-colors) * [Resizing columns](#resizing-columns) * [Overriding fzf options](#overriding-fzf-options) * [Overriding during cheats selection](#overriding-during-cheats-selection) * [Overriding during values selection](#overriding-during-values-selection) * [Overriding for all cases](#overriding-for-all-cases) * [Defining your own delimiter](#defining-your-own-delimiter) ## Paths and Environment Variables On the technical side, navi uses the `directories-next` crate for rust, which defines platform-specific locations to store the configuration files, the cache and other types of files an application might need. > [!TIP] > For example, this is why cheatsheets are being stored in `~/Library/Application Support/navi` on macOS. > [!NOTE] > Interested on how `directories-next` works?\ > Go see their `crates.io` page: [crates.io/crates/directories-next](https://crates.io/crates/directories-next) ### The default configuration file path During the compilation of navi, the default configuration file path is set by the `$NAVI_CONFIG` environment variable.\ If it is not set, it fallbacks to `~/.config/navi/config.yaml`. You can check your default configuration file path with the info subcommand, see [/docs/usage/commands/info/](/docs/usage/commands/info/README.md#default-configuration-path) for more details. ### Cheatsheets paths Navi checks the paths in the following order until it finds a value: 1. the `$NAVI_PATH` environment variable 2. the configuration file 3. The default value of navi #### The default cheatsheets path By default, navi stores the cheatsheets in the `~/.local/share/navi/cheats/` directory. You can check your default cheatsheets path with the info subcommand, see [/docs/usage/commands/info/](/docs/usage/commands/info/README.md#default-cheatsheets-path) for more details. #### Defining the cheatsheets path with the environment variable The cheatsheets path can be defined using the `$NAVI_PATH` environment variable in a colon-separated list, for example: ```sh export NAVI_PATH='/path/to/a/dir:/path/to/another/dir:/yet/another/dir' ``` #### Defining the cheatsheets path in the configuration file You can define the cheatsheets path in the configuration file with the following syntax: ```yaml cheats: paths: - /path/to/some/dir # on unix-like os - F:\\path\\to\\dir # on Windows ``` ##### [DEPRECATED] - Using the `path` directive Until `2.17.0`, you could define your cheatsheets path with the `path` directive with the following syntax: ```yaml cheats: path: /path/to/some/dir ``` The directive is now deprecated and will be removed in `2.27.0`. ## Customization ### Changing colors #### fzf color scheme You can change the color scheme of `fzf` by overriding fzf options. > [!NOTE] > See [@junegunn/fzf/wiki/Color-schemes](https://github.com/junegunn/fzf/wiki/Color-schemes) and > [#overriding-fzf-options](#overriding-fzf-options) for more details. #### Navi colors You can change the text color for each column of navi in the configuration file with the following syntax: ```yaml style: tag: color: comment: color: snippet: color: ``` Below is an example of what to do if you'd like navi to look like the French flag: - `config.yaml`: ```yaml style: tag: color: blue comment: color: white snippet: color: red ``` - The result: ### Resizing columns You can change the column width of each column of navi in the configuration file with the following syntax: ```yaml style: tag: width_percentage: min_width: comment: width_percentage: min_width: snippet: width_percentage: min_width: ``` ### Overriding fzf options You can override fzf options for two different cases: - During the cheats selection Navi exposes the `overrides` directive in the configuration file and the `NAVI_FZF_OVERRIDES` environment variable. - During the pre-defined variable values selection Navi exposes the `overrides_var` directive in the configuration file and the `NAVI_FZF_OVERRIDES_VAR` environment variable. For all cases, navi exposes the `FZF_DEFAULT_OPTS` environment variable. #### Overriding during cheats selection If you want to do the override with `--height 3`, you can do it with the following syntax in the configuration file: ```yaml finder: command: fzf overrides: --height 3 ``` But you can also define the environment variable like this: ```bash export NAVI_FZF_OVERRIDES='--height 3' ``` #### Overriding during values selection If you want to do the override with `--height 3`, you can do it with the following syntax in the configuration file: ```yaml finder: command: fzf overrides_var: --height 3 ``` But you can also define the environment variable like this: ```bash export NAVI_FZF_OVERRIDES_VAR='--height 3' ``` #### Overriding for all cases You can define the environment variable like this: ```bash export FZF_DEFAULT_OPTS="--height 3" ``` > [!NOTE] > See [@junegunn/fzf](https://github.com/junegunn/fzf#layout) for more details on `$FZF_DEFAULT_OPTS`. ## Defining your own delimiter Navi allows you to define your own delimiter to parse the selected result for a variable in your cheats.\ It is equivalent to defining `--delimiter` used with `--column`. You can define it as such: ```yaml finder: delimiter_var: ### By default the expression is \s\s+ ``` > [!CAUTION] > Defining the delimiter via the configuration file means that Navi will use this delimiter by default for > every variable using the `--column` instruction. You can override this configuration with the `--delimiter` instruction in the variable definition of your cheat.\ See [/docs/cheatsheet/syntax/](/docs/cheatsheet/syntax/README.md#advanced-variable-options) for more details. ## Changing shell You can change the shell that is used inside navi. ```yaml shell: command: bash finder_command: bash ``` `shell.command` is used to execute commands that generate possible values for variables. `shell.finder_command` is used inside fzf. For example, suppose you have the following cheat sheet. ``` # ISO 8061 date -I $ iso_unit: echo -e 'date\nhours\nminutes\nseconds\nns' ``` The command `echo -e 'date\nhours\nminutes\nseconds\nns'` is executed in the shell specified by `shell.command`. ### Use bash on Windows On Windows, there are several bash environments available, including MSYS2's bash, Git Bash, and [w64devkit](https://github.com/skeeto/w64devkit)'s bash. The w64devkit's bash isn't actually bash, but it can be used just like bash. Here is an example of using Git Bash. ```yaml shell: command: "\"C:/Program Files/Git/bin/bash.exe\"" finder_command: "C:/Program Files/Git/bin/bash.exe" forward_slash_path: true ``` If the path to the executable contains spaces, it must be quoted in the `shell.command`. Unlike `shell.command`, `shell.finder_command` does not require the path to be quoted even if it contains spaces. Additionaly, `shell.forward_slash_path` must be set to `true`. `shell.forward_slash_path: true` can be used with bash environments that interpret paths with forward slashes (e.g., `C:/path/to/bash.exe`). Other than Windows, setting `shell.forward_slash_path` has no effect. --- ## File: docs/cheatsheet/repositories/README.md # Cheatsheet repositories * [Cheatsheet repositories](#cheatsheet-repositories) * [About](#about) * [Importing cheatsheet repositories](#importing-cheatsheet-repositories) * [Submitting cheatsheets](#submitting-cheatsheets) * [Auto-updating repositories](#auto-updating-repositories) ## About Navi lets you work with what we call `cheatsheet repositories`, they are git repositories and mainly consists of `.cheat` files. This page is dedicated to the information you might need to work with `cheatsheet repositories`. ## Importing cheatsheet repositories You can import `cheatsheet repositories` with the `repo add` subcommand.\ See [/docs/usage/commands/repo](/docs/usage/commands/repo/README.md#importing-cheatsheet-repositories) for more details. ## Submitting cheatsheets The featured repository for cheatsheets is [denisidoro/cheats](https://github.com/denisidoro/cheats), feel free to open a PR[^1] there for me to include your contributions. In order to add your own repository as a featured cheatsheet repo, please [edit this file](https://github.com/denisidoro/cheats/edit/master/featured_repos.txt) and open a PR[^1]. ## Auto-updating repositories Right now, **navi** doesn't have support for auto-updating out of the box. However, you can achieve this by using `git` and `crontab`. - First make sure you cloned your repo using `git` to the correct folder: ```sh user="" repo="" git clone "https://github.com/${user}/${repo}" "$(navi info cheats-path)/${user}__${repo}" ``` - Then, add a cron job: ```sh crontab -e */0 11 * * * bash -c 'cd "$(/usr/local/bin/navi info cheats-path)/__" && /usr/local/bin/git pull -q origin master' ``` > [!NOTE] > Please note the cron job above is just an example **AND** you should edit it accordingly: > >- In this example, the cron job is triggered every day at 11am. > > You might want to check out [crontab guru](https://crontab.guru/) regarding crontab. > >- The full paths to `navi` and `git` may differ in your setup. > > Check their actual values using `which` as `which `. > >- Don't forget to replace `__` with the actual folder name [^1]: A *PR* is short for Pull Request