Mirrors/navi
1
0
Fork 0
mirror of https://github.com/denisidoro/navi.git synced 2026-01-23 02:14:19 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'new-docs' of github.com:alexis-opolka/navi into alexis-opolka-new-docs

Browse source
This commit is contained in:
alexis-opolka 2025-05-04 12:37:13 +02:00
commit 445f9be247
32 changed files with 1334 additions and 712 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/README.md Normal file
View file

@ -0,0 +1,41 @@
# Navi <img src="https://raw.githubusercontent.com/denisidoro/navi/master/assets/icon.png" alt="icon" height="28px"/> [![Actions Status](https://github.com/denisidoro/navi/workflows/CI/badge.svg)](https://github.com/denisidoro/navi/actions) ![GitHub release](https://img.shields.io/github/v/release/denisidoro/navi?include_prereleases)
## Table of Contents
<!-- TOC -->
* [Navi <img src="https://raw.githubusercontent.com/denisidoro/navi/master/assets/icon.png" alt="icon" height="28px"/> ![Actions Status](https://github.com/denisidoro/navi/workflows/CI/badge.svg) ![GitHub release](https://img.shields.io/github/v/release/denisidoro/navi?include_prereleases)](#navi-img-srchttpsrawgithubusercontentcomdenisidoronavimasterassetsiconpng-alticon-height28px--)
* [Table of Contents](#table-of-contents)
* [About](#about)
* [Navi Pros](#navi-pros)
* [Similar tools](#similar-tools)
* [Etymology](#etymology)
<!-- TOC -->
## About
Navi is an interactive cheatsheet tool for the command-line.\
It allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands.
[![Demo](https://asciinema.org/a/406461.svg)](https://asciinema.org/a/406461)
It uses [fzf](https://github.com/junegunn/fzf), [skim](https://github.com/lotabout/skim), or [Alfred](https://www.alfredapp.com/) under the hood and it can be either used as a command or as a shell widget (_à la_ Ctrl-R).
## Navi 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
## Similar tools
There are many similar projects out there ([beavr](https://github.com/denisidoro/beavr), [bro](https://github.com/hubsmoke/bro), [cheat](https://github.com/cheat/cheat), [cheat.sh](https://github.com/chubin/cheat.sh), [cmdmenu](https://github.com/amacfie/cmdmenu), [eg](https://github.com/srsudar/eg), [how2](https://github.com/santinic/how2), [howdoi](https://github.com/gleitz/howdoi), [Command Line Interface Pages](https://github.com/command-line-interface-pages) and [tldr](https://github.com/tldr-pages/tldr), to name a few).
They are excellent projects, but **navi** remains unique in the following ways:
- it's natural to write cheatsheets tailored to your needs
- arguments are neither hardcoded nor a simple template
## Etymology
[Navi](https://zelda.gamepedia.com/Navi) is a character from [The Legend of Zelda Ocarina of Time](https://zelda.gamepedia.com/Ocarina_of_Time) that provides [Link](https://zelda.gamepedia.com/Link) with a variety of clues to help him solve puzzles and make progress in his quest.

64
docs/cheatsheet/README.md Normal file
View file

@ -0,0 +1,64 @@
# Navi cheatsheets
<!-- TOC -->
* [Navi cheatsheets](#navi-cheatsheets)
* [Working with `cheatsheet repositories`](#working-with-cheatsheet-repositories)
* [Manually adding cheatsheets to navi](#manually-adding-cheatsheets-to-navi)
* [Choosing between queries and selection with variables](#choosing-between-queries-and-selection-with-variables)
* [Using cheatsheets from other tools](#using-cheatsheets-from-other-tools)
<!-- TOC -->
## Working with `cheatsheet repositories`
Navi works best with what we call `cheatsheet repositories`, for more details see [cheatsheet/repositories](repositories/README.md).
## Manually adding cheatsheets to navi
If you don't want to work with `cheatsheet repositories`, you can manually add your
cheatsheets to navi by putting them into the `cheats_path` of your platform.
You can find out your path using the [info](/docs/usage/commands/info/README.md) subcommands
but a quick working command to go there would be:
- Before 2.25.0
```bash
cd $(navi info cheats-path)
```
- After 2.25.0
```bash
cd $(navi info default-cheats-path)
```
## Choosing between queries and selection with variables
Navi lets you use different methods to fill a variable value, when prompted.
| Keyboard key | Preference |
|:------------------:|:--------------------------:|
| <kbd> tab </kbd> | The query is preferred |
| <kbd> enter </kbd> | The selection is preferred |
It means if you enter the <kbd> tab </kbd> key, navi will let you enter the value.
## Using cheatsheets from other tools
> [!WARNING]
> Navi **DOESN'T SUPPORT** as of now importing cheatsheets from other tools
> but is able to **work with** TLDR and Cheat.sh.
![Demo](https://user-images.githubusercontent.com/3226564/91878474-bae27500-ec55-11ea-8b19-17876178e887.gif)
You can use cheatsheets from [tldr](https://github.com/tldr-pages/tldr) by running:
```sh
navi --tldr <query>
```
You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running:
```sh
navi --cheatsh <query>
```

1
docs/cheatsheet/getting-started/README.md Normal file
View file

@ -0,0 +1 @@
# Cheatsheets - Getting started

63
docs/cheatsheet/repositories/README.md Normal file
View file

@ -0,0 +1,63 @@
# Cheatsheet repositories
<!-- TOC -->
* [Cheatsheet repositories](#cheatsheet-repositories)
* [About](#about)
* [Importing cheatsheet repositories](#importing-cheatsheet-repositories)
* [Submitting cheatsheets](#submitting-cheatsheets)
* [Auto-updating repositories](#auto-updating-repositories)
<!-- TOC -->
## 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="<user>"
repo="<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)/<user>__<repo>" && /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 <program>`.
>
>- Don't forget to replace `<user>__<repo>` with the actual folder name
[^1]: A *PR* is short for Pull Request

248
docs/cheatsheet/syntax/README.md Normal file
View file

@ -0,0 +1,248 @@
# The syntax of a Navi cheatsheet
<!-- TOC -->
* [The syntax of a Navi cheatsheet](#the-syntax-of-a-navi-cheatsheet)
* [Syntax overview](#syntax-overview)
* [Variables](#variables)
* [Advanced variable options](#advanced-variable-options)
* [Variable dependency](#variable-dependency)
* [Implicit dependencies](#implicit-dependencies)
* [Explicit dependencies](#explicit-dependencies)
* [Variable as multiple arguments](#variable-as-multiple-arguments)
* [Extending cheats](#extending-cheats)
* [Multiline commands/snippets](#multiline-commandssnippets)
* [Aliases](#aliases)
<!-- TOC -->
## Syntax overview
Cheats are described in cheatsheet files.\
A cheatsheet is a file that has a `.cheat` or `.cheat.md` extension and looks like this:
```sh
% git, code
# Change branch
git checkout <branch>
$ branch: git branch | awk '{print $NF}'
```
A cheatsheet can have the following elements:
| Element | Syntax | Description |
|:--------------------------------:|:------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| Tags as cheat titles | `%` | Lines starting with this character are considered the start of a new cheat command and should contain tags. |
| Cheat Description | `#` | Lines starting with this character should be the description of the cheat you're writing. |
| Cheat Comments (or Metacomments) | `;` | Lines starting with this character will be ignored by navi but they can be great as editor's comments. |
| Pre-defined variables | `$` | Lines starting with this character should contain commands that generate a list of possible values. <br/> <br/> :information_source: See [#variables](#variables) for more details. |
| Extended cheats | `@` | Lines starting with this character should contain tags associated to other defined cheats. <br/> <br/> :information_source: See [#extending-cheats](#extending-cheats) for more details. |
| Executable commands | N/A | All other non-empty lines are considered as executable commands. |
> [!TIP]
> If you are editing cheatsheets in Visual Studio Code, you could enable syntax highlighting
> by installing this extension: [@yanivmo/navi-cheatsheet-language](https://marketplace.visualstudio.com/items?itemName=yanivmo.navi-cheatsheet-language).
## Variables
Variables are defined with brackets inside executable commands (e.g. `<branch>`).\
Variable names should only include alphanumeric characters and `_`.
You can show suggestions by using the Pre-defined variable lines (i.e. lines starting with`$`).\
Otherwise, the user will be able to type any value for it.
### Advanced variable options
For Pre-Defined variable lines, you can use `---` to customize the behavior of `fzf`
or how the value is going to be used.
Below are examples of such customization:
- We define what column to use, the number of header lines and a delimiter between values.
```sh
# This will pick the 3rd column and use the first line as header
docker rmi <image_id>
$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
```
- We modify the output values of a command
```shell
# Even though "false/true" is displayed, this will print "0/1"
echo <mapped>
$ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0"
```
The supported parameters are:
| Parameter | Description |
|:------------------------|:------------------------------------------------------------------------------------------|
| `--column <number>` | `<number>` is the column number to extract from the result. |
| `--map <bash_code>` | **_[EXPERIMENTAL]_** `<bash_code>` is a map function to apply to the variable value. |
| `--prevent-extra` | **_[EXPERIMENTAL]_** This parameter will limit the user to select one of the suggestions. |
| `--fzf-overrides <arg>` | **_[EXPERIMENTAL]_** `<arg>` is an arbitrary argument to override `fzf` behaviour. |
| `--expand` | **_[EXPERIMENTAL]_** This parameter will convert each line into a separate argument. |
In addition, it's possible to forward the following parameters to `fzf`:
| Parameter forwarded to `fzf` |
|:-----------------------------|
| `--multi` |
| `--header-lines <number>` |
| `--delimiter <regex>` |
| `--query <text>` |
| `--filter <text>` |
| `--header <text>` |
| `--preview <bash_code>` |
| `--preview-window <text>` |
### Variable dependency
Pre-Defined variables can refer other pre-defined variables in two different ways, an implicit and explicit way.
#### Implicit dependencies
An implicit dependency is when you refer another variable with the same syntax used in
executable commands (i.e. `<variable>`).
Below is an example of using implicit dependencies to construct a path:
```sh
# Should print /my/pictures/wallpapers
echo "<wallpaper_folder>"
$ pictures_folder: echo "/my/pictures"
$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
```
#### Explicit dependencies
An explicit dependency is when you prepend a dollar sign (i.e. `$`) to the variable name.
Below is an example of using explicit dependencies to give multiple choices:
```sh
# If you select "hello" for <x>, the possible values of <y> will be "hello foo" and "hello bar"
echo <x> <y>
# If you want to ignore the contents of <x> and only print <y>
: <x>; echo <y>
$ x: echo "hello hi" | tr ' ' '\n'
$ y: echo "$x foo;$x bar" | tr ';' '\n'
```
### Variable as multiple arguments
Variables can have multiple arguments,
below is an example of using multiple arguments to cat multiple files at the same time.
```sh
# This will result into: cat "file1.json" "file2.json"
cat <jsons>
$ jsons: find . -iname '*.json' -type f -print --- --multi --expand
```
## Extending cheats
Navi allows you to extend a cheat context with `Extended cheats` lines (i.e. starting with `@`).\
If you put the same tags from another cheat, you will be able to share the same context and will
be able to use the same variables, for example.
```sh
% dirs, common
$ pictures_folder: echo "/my/pictures"
% wallpapers
@ dirs, common
# Should print /my/pictures/wallpapers
echo "<pictures_folder>/wallpapers"
% screenshots
@ dirs, common
# Should print /my/pictures/screenshots
echo "<pictures_folder>/screenshots"
```
## Multiline commands/snippets
Commands can be multiline, we call them snippets.
- You can write them as follows:
```sh
% bash, foo
# This will output "foo\nyes"
echo foo
true \
&& echo yes \
|| echo no
```
- Or, you can place them inside Markdown code blocks, delimited by triple backticks (```` ``` ````):
````sh
% git, code
# Change branch
```sh
git checkout <branch>
```
$ branch: git branch | awk '{print $NF}'
````
## Aliases
**navi** doesn't have support for aliases as first-class citizens at the moment.\
However, it is easy to create aliases using **navi** + a few conventions.
> [!CAUTION]
> The examples below will only work if you use **navi** as a shell scripting tool.
>
> See [/docs/usage/shell-scripting](/docs/usage/shell-scripting/README.md) for more details.
For example, suppose you decide to end some of your commands with `:: <some_alias>`:
```bash
% aliases
# This is one command :: el
echo lorem ipsum
# This is another command :: ef
echo foo bar
```
You could add something similar to this in your `.bashrc`-like file:
```bash
navialias() {
navi --query ":: $1" --best-match
}
alias el="navialias el"
alias ef="navialias ef"
```
If you don't want to use these conventions, you can even add full comments in your aliases:
```bash
navibestmatch() {
navi --query "$1" --best-match
}
alias el="navibestmatch 'This is one command'"
alias ef="navibestmatch 'This is another command'"
```

75
docs/cheatsheet_repositories.md
View file

@ -1,75 +0,0 @@
## Cheatsheet repositories
- [Browsing through cheatsheet repositories](#browsing-through-cheatsheet-repositories)
- [Importing cheatsheets](#importing-cheatsheets)
- [Adding your own cheatsheets](#adding-your-own-cheatsheets)
- [Submitting cheatsheets](#submitting-cheatsheets)
- [Using cheatsheets from other tools](#using-cheatsheets-from-other-tools)
- [Auto-updating repositories](#auto-updating-repositories)
### Browsing through cheatsheet repositories
You can find cheatsheet repositories with:
```sh
navi repo browse
```
### Importing cheatsheets
You can import cheatsheets from any git repository that includes `.cheat` files:
```sh
navi repo add https://github.com/denisidoro/cheats
```
### Adding your own cheatsheets
You can either start a git repo with cheatsheets and import it as described above or you can add them directly to [data_dir](https://github.com/soc/dirs-rs#Features)`/navi`.
### Submitting cheatsheets
The main repository for cheatsheets is [denisidoro/cheats](https://github.com/denisidoro/cheats). Feel free to open a PR 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). This list will be displayed when `navi repo browse` is run.
### Using cheatsheets from other tools
![Demo](https://user-images.githubusercontent.com/3226564/91878474-bae27500-ec55-11ea-8b19-17876178e887.gif)
You can use cheatsheets from [tldr](https://github.com/tldr-pages/tldr) by running:
```sh
navi --tldr <query>
```
You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running:
```sh
navi --cheatsh <query>
```
### 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="<user>"
repo="<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)/<user>__<repo>" && /usr/local/bin/git pull -q origin master'
```
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. [crontab guru](https://crontab.guru/) may come in handy if you want to change this value
- The full paths to `navi` and `git` may differ in your setup. Check their actual values using `which navi` and `which git`
- Don't forget to replace `<user>__<repo>` with the actual folder name

201
docs/cheatsheet_syntax.md
View file

@ -1,201 +0,0 @@
## Cheatsheet syntax
- [Syntax overview](#syntax-overview)
- [Folder structure](#folder-structure)
- [Variables](#variables)
- [Advanced variable options](#advanced-variable-options)
- [Variable dependency](#variable-dependency)
- [Multiline snippets](#multiline-snippets)
- [Variable as multiple arguments](#variable-as-multiple-arguments)
- [Aliases](#aliases)
### Syntax overview
Cheatsheets are described in `.cheat` (or `.cheat.md`) files that look like this:
```sh
% git, code
# Change branch
git checkout <branch>
$ branch: git branch | awk '{print $NF}'
```
Lines starting with:
- `%`: determine the start of a new cheatsheet and should contain tags
- `#`: should be descriptions of commands
- `;`: are ignored. You can use them for metacomments
- `$`: should contain commands that generate a list of possible values for a given argument [:information_source:](#variables)
- `@`: should contain tags whose associated cheatsheet you want to base on [:information_source:](#extending-cheatsheets)
All the other non-empty lines are considered as executable commands.
> [!TIP]
> If you are editing cheatsheets in Visual Studio Code, you could enable syntax highlighting
> by installing this extension: [@yanivmo/navi-cheatsheet-language](https://marketplace.visualstudio.com/items?itemName=yanivmo.navi-cheatsheet-language).
You can place commands in code blocks fenced with triple backticks (```` ``` ````).
````sh
% git, code
# Change branch
```sh
git checkout <branch>
```
$ branch: git branch | awk '{print $NF}'
````
### Variables
The interface prompts for variable names inside brackets (eg `<branch>`).
Variable names should only include alphanumeric characters and `_`.
If there's a corresponding line starting with `$` for a variable, suggestions will be displayed. Otherwise, the user will be able to type any value for it.
If you hit `<tab>` the query typed will be preferred. If you hit `<enter>` the selection will be preferred.
### Advanced variable options
For lines starting with `$` you can use `---` to customize the behavior of `fzf` or how the value is going to be used:
```sh
# This will pick the 3rd column and use the first line as header
docker rmi <image_id>
# Even though "false/true" is displayed, this will print "0/1"
echo <mapped>
$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
$ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0"
```
The supported parameters are:
- `--column <number>`: extracts a single column from the selected result
- `--map <bash_code>`: _(experimental)_ applies a map function to the selected variable value
- `--prevent-extra`: _(experimental)_ limits the user to select one of the suggestions
- `--fzf-overrides <arg>`: _(experimental)_ applies arbitrary `fzf` overrides
- `--expand`: _(experimental)_ converts each line into a separate argument
In addition, it's possible to forward the following parameters to `fzf`:
- `--multi`
- `--header-lines <number>`
- `--delimiter <regex>`
- `--query <text>`
- `--filter <text>`
- `--header <text>`
- `--preview <bash_code>`
- `--preview-window <text>`
### Variable dependency
The command for generating possible inputs can implicitly refer other variables by using the `<varname>` syntax:
```sh
# Should print /my/pictures/wallpapers
echo "<wallpaper_folder>"
$ pictures_folder: echo "/my/pictures"
$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
```
If you want to make dependencies explicit, you can use the `$varname` syntax:
```sh
# If you select "hello" for <x>, the possible values of <y> will be "hello foo" and "hello bar"
echo <x> <y>
# If you want to ignore the contents of <x> and only print <y>
: <x>; echo <y>
$ x: echo "hello hi" | tr ' ' '\n'
$ y: echo "$x foo;$x bar" | tr ';' '\n'
```
### Extending cheatsheets
With the `@ same tags from other cheatsheet` syntax you can reuse the same variable in multiple cheatsheets.
```sh
% dirs, common
$ pictures_folder: echo "/my/pictures"
% wallpapers
@ dirs, common
# Should print /my/pictures/wallpapers
echo "<pictures_folder>/wallpapers"
% screenshots
@ dirs, common
# Should print /my/pictures/screenshots
echo "<pictures_folder>/screenshots"
```
### Multiline snippets
Commands may be multiline:
```sh
# This will output "foo\nyes"
echo foo
true \
&& echo yes \
|| echo no
```
### Variable as multiple arguments
```sh
# This will result into: cat "file1.json" "file2.json"
cat <jsons>
$ jsons: find . -iname '*.json' -type f -print --- --multi --expand
```
### Aliases
**navi** doesn't have support for aliases as first-class citizens at the moment.
However, it is trivial to create aliases using **navi** + a few conventions.
For example, suppose you decide to end some of your commands with `:: <some_alias>`:
```bash
% aliases
# This is one command :: el
echo lorem ipsum
# This is another command :: ef
echo foo bar
```
Then, if you use **navi** as a [shell scripting tool](shell_scripting.md), you could add something similar to this in your `.bashrc`-like file:
```bash
navialias() {
navi --query ":: $1" --best-match
}
alias el="navialias el"
alias ef="navialias ef"
```
If you don't want to use these conventions, you can even add full comments in your aliases:
```bash
navibestmatch() {
navi --query "$1" --best-match
}
alias el="navibestmatch 'This is one command'"
alias ef="navibestmatch 'This is another command'"
```

233
docs/configuration/README.md Normal file
View file

@ -0,0 +1,233 @@
# Configuring Navi
Navi allows you to configure it with a YAML configuration.
<!-- TOC -->
* [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)
<!-- TOC -->
## 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: <your color for tags>
comment:
color: <your color for comments>
snippet:
color: <you color for snippets>
```
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:
![navi-custom-colors](https://github.com/user-attachments/assets/d80352c5-d888-43e6-927d-805a8de1a7e2)
### 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: <width relative to the terminal window>
min_width: <width as number of characters>
comment:
width_percentage: <width relative to the terminal window>
min_width: <width as number of characters>
snippet:
width_percentage: <width relative to the terminal window>
min_width: <width as number of characters>
```
### 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: <your-regex-delimiter> ### 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.

47
docs/contributions/README.md Normal file
View file

@ -0,0 +1,47 @@
# Navi contributors
This section is about the ways you can contribute to Navi and its ecosystem.
<!-- TOC -->
* [Navi contributors](#navi-contributors)
* [How to contribute to Navi](#how-to-contribute-to-navi)
* [Versioning Scheme](#versioning-scheme)
* [Deprecation of features](#deprecation-of-features)
<!-- TOC -->
## 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.

6
docs/contributions/bugs/README.md Normal file
View file

@ -0,0 +1,6 @@
# 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 [https://github.com/denisidoro/navi/issues/](https://github.com/denisidoro/navi/issues/) to open an issue.

50
docs/contributions/code/README.md Normal file
View file

@ -0,0 +1,50 @@
# 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).

32
docs/contributions/documentation/README.md Normal file
View file

@ -0,0 +1,32 @@
# 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
| | +-- <topic-examples>
| +-- src
| | +-- <topic-source-files>
| | | +-- <sorted-by-type>
| +-- <topic>
| | +-- 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.

14
docs/alfred.md → docs/deprecated/Alfred/README.md
View file

@ -1,15 +1,15 @@
## Alfred
# 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).
![Alfred demo](https://user-images.githubusercontent.com/3226564/80294838-582b1b00-8743-11ea-9eb5-a335d8eed833.gif)
### Note
Support for alfred has been removed.
The latest version which has some support for it is [2.15.1](https://github.com/denisidoro/navi/releases/tag/v2.15.1).
### Instructions
- make sure you have [Alfred Powerpack](https://www.alfredapp.com/powerpack/)

12
docs/cheat_example.cheat → docs/examples/cheatsheet/example.cheat
View file

@ -1,6 +1,6 @@
% first cheat
# print something
echo "My name is <name>!"
$ name: whoami
% first cheat
# print something
echo "My name is <name>!"
$ name: whoami

0
docs/navi.cheat → docs/examples/cheatsheet/navi.cheat
View file

1
docs/config_file_example.yaml → docs/examples/configuration/config-example.yaml
View file

@ -23,7 +23,6 @@ finder:
# paths:
# - /path/to/some/dir # on unix-like os
# - F:\\path\\to\\dir # on Windows
# path: /path/to/some/dir # (DEPRECATED) equivalent to the --path option
# search:
# tags: git,!checkout # equivalent to the --tag-rules option

152
docs/installation.md
View file

@ -1,152 +0,0 @@
## Installation
- [Installing the main binary](#installing-the-main-binary)
- [Using Homebrew](#using-homebrew)
- [Using Gentoo](#using-gentoo)
- [Using nix](#using-nix)
- [Using cargo](#using-cargo)
- [Using install script](#using-install-script)
- [Downloading pre-compiled binaries](#downloading-pre-compiled-binaries)
- [Building from source](#building-from-source)
- [Other package managers](#other-package-managers)
- [Installing the shell widget](#installing-the-shell-widget)
### Installing the main binary
#### Using [Homebrew](http://brew.sh/)
```sh
brew install navi
```
#### Using [Gentoo](https://gentoo.org/)
Be sure to [enable](https://wiki.gentoo.org/wiki/Ebuild_repository) the [GURU overlay](https://gpo.zugaina.org/Overlays/guru/app-misc/navi).
```sh
emerge -a app-misc/navi
```
#### Using [pacman](https://wiki.archlinux.org/title/Pacman)
```sh
pacman -S navi
```
#### Using [nix](https://nixos.org/)
```sh
nix-env -iA nixpkgs.navi
```
#### Using [cargo](https://github.com/rust-lang/cargo)
```bash
cargo install --locked navi
```
#### Using [choco](https://community.chocolatey.org/packages/navi)
For Windows user, using powershell
1. Install package via choco
```bash
choco install navi
```
2. Create `$env:USERPROFILE\AppData\Roaming\navi\config.yaml` and override `shell.command` as per [config_file_example.yaml](./config_file_example.yaml)
```
style:
tag:
color: cyan
comment:
color: grey
snippet:
color: white
shell:
command: powershell
```
Remark: Above example also adds custom colors for better readability in case you use standard blue for your Powershell
#### Using install script
```bash
bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
# (optional) to set directories:
# BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
```
#### Downloading pre-compiled binaries
- download the correct binary [here](https://github.com/denisidoro/navi/releases/latest)
- extract the content to your `$PATH`
#### Building from source
```bash
git clone https://github.com/denisidoro/navi ~/.navi
cd ~/.navi
make install
# (optional) to set the install directory:
# make BIN_DIR=/usr/local/bin install
```
##### Compile time environment variables
**navi** supports environment variables at compile time that modify the behavior of the binary at runtime:
- `NAVI_PATH` (directory path value): If the `cheats` directory in the user's directory does not exist, **navi** uses this path (if it exists), as a fallback location to look for cheat files. Use case: system-wide installed, shared used cheatsheets folder.
- `NAVI_CONFIG` (file path value): If the `config.yaml` file in the user's directory does not exist, **navi** uses this path (if it exists), as a fallback location to look for a configuration file. Use case: system-wide installed, shared used configuration file.
#### Other package managers
You can find **navi** for more package managers by clicking on the image below:
[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
Feel free to be the maintainer of **navi** for any package manager you'd like!
### Installing the shell widget
If you want to install it, add this line to your `.bashrc`-like file:
```sh
# bash
eval "$(navi widget bash)"
# zsh
eval "$(navi widget zsh)"
# fish
navi widget fish | source
# elvish
eval (navi widget elvish | slurp)
# xonsh
# xpip install xontrib-navi # ← run in your xonsh session to install xontrib
xontrib load navi # ← add to your xonsh run control file
```
#### Nushell
Due to Nushell's [unique design](https://www.nushell.sh/book/thinking_in_nu.html#think-of-nushell-as-a-compiled-language), it is not possible to `eval` a piece of code dynamically like in other shells therefore the integration process is a bit more involved. Here is an example:
1. run `^navi widget nushell | save ($nu.default-config-dir | path join "navi-integration.nu")`
2. add the following lines to `config.nu`:
```nushell
source ($nu.default-config-dir | path join "navi-integration.nu")
```
By default, `Ctrl+G` is assigned to launching **navi** (in xonsh can be customized with `$X_NAVI_KEY`, see [xontrib-navi](https://github.com/eugenesvk/xontrib-navi) for details).
There's currently no way to customize the widget behavior out-of-the-box. If you want to change the keybinding or the **navi** flags used by the widget, please:
1. run, e.g., `navi widget bash` in your terminal
2. copy the output
3. paste the output in your `.bashrc`-like file
4. edit the contents accordingly

147
docs/installation/README.md Normal file
View file

@ -0,0 +1,147 @@
# 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:
[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions)
Feel free to be the maintainer of **navi** for any package manager you'd like!

157
docs/navi_config.md
View file

@ -1,157 +0,0 @@
- [Paths and Environment Variables](#paths-and-environment-variables)
- [Config file path](#config-file-path)
- [Cheat sheet paths](#cheat-sheet-paths)
- [Logging](#logging)
- [Customization](#customization)
- [Changing colors](#changing-colors)
- [Resizing columns](#resizing-columns)
- [Overriding fzf options](#overriding-fzf-options)
- [Defining your own delimiter](#defining-your-own-delimiter)
# Paths and Environment Variables
Navi uses the [`directories-next`](https://crates.io/crates/directories-next) package, which
defines platform-specific standard locations of directories for config, cache and other data (Mac users, this is why your files are being stored in `~/Library/Application Support/navi`).
## Config file path
The default config file path is set by the `$NAVI_CONFIG` environment variable.\
If it is not set, it fallbacks to `~/.config/navi/config.yaml` in most cases.
There are available commands for you to see which path is used or its default value.
### Default config path
There are two `info` commands available for the users to know and understand
what is the default path for the configuration of navi.
> [!NOTE]
> The `info` commands DO NOT return the current value used by navi but exist
> as informative commands, they do not represent navi's running configuration.
- For navi `2.25.0` and later:
```sh
navi info default-config-path
```
- For navi versions earlier than `2.25.0`:
```sh
navi info config-path
```
> [!CAUTION]
> Since navi `2.25.0`, the `info config-path` command is deprecated.
> We recommend you to use `info default-config-path` instead.
### Example config file
You can get an example of a config file by running:
```sh
navi info config-example
```
> [!NOTE]
> You can also get the example file [here](./config_file_example.yaml).
To turn this example into your config file, you just need to run:
```sh
navi info config-example > "$(navi info config-path)"
```
## Cheat sheet paths
The default `.cheat` files paths are defined in the `$NAVI_PATH` environment variable in a colon-separated list, e.g.,
```sh
export NAVI_PATH='/path/to/a/dir:/path/to/another/dir:/yet/another/dir'
```
If this environment variable is unset or if all directories do not exist, `navi` uses the [paths defined in the config file](https://github.com/denisidoro/navi/blob/master/docs/config_file_example.yaml#L21-L24). Finally, if there is no config file or if the `.cheat` file paths was not set, the default `.cheat` file paths fallbacks to `~/.local/share/navi/cheats/`. The command
```sh
navi info cheats-path
```
prints to you all paths used to search for `.cheat` files.
You can also add other paths at runtime by running `navi` with the `--path` option and a colon-separated paths list, e.g.,
```sh
navi --path '/some/dir:/other/dir'
```
It's irrelevant the directory structure within each path. They can even be all in a single file if you wish, as long as you split them accordingly with lines starting with `%`.
Despite `$NAVI_PATH` being set, it will not be used when installing cheat sheets directly via navi's own commands. For example when running `navi add repo <repo>`, the default paths as per the `directories-next` package will still be used. To avoid this, you may simply clone repos via a regular `git clone` command, directly into `$NAVI_PATH`.
> [!NOTE]
> `navi info cheats-path` and `navi info config-path` display the *default* path, not
> the path set by the user. [It is known that this is a little misleading!](https://github.com/denisidoro/navi/issues/664#issuecomment-1004721178).
# Logging
The log file will be created under the same directory where the config locates.
And you can use the `RUST_LOG` env to set the log level, e.g. `RUST_LOG=debug navi`.
# Customization
## Changing colors
You can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes) by [overriding fzf options](#overriding-fzf-options).
In addition, you can change the text color for each column by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.
## Resizing columns
You can change the column widths by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.
## Overriding fzf options
Let's say you want to override [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#layout) with `--height 3`.
This can be overridden in the following ways:
```sh
# if you want to override only when selecting snippets
navi --fzf-overrides '--height 3'
# alternatively, using an environment variable in your .bashrc-like file:
export NAVI_FZF_OVERRIDES='--height 3'
# if you want to override only when selecting argument values
navi --fzf-overrides-var '--height 3'
# alternatively, using an environment variable in your .bashrc-like file:
export NAVI_FZF_OVERRIDES_VAR='--height 3'
# if you want to override for all cases
FZF_DEFAULT_OPTS="--height 3" navi
```
In addition, this can be set by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.
## 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: <your-regex-delimiter> ### 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 cheatsheet.
It can be overriden like this:
```yaml
echo <image_id>
$ image_id: ... --- --column 3 --header-lines 1 --delimiter '\s\s+' # <-- This variable uses \s\s+ as a delimiter
$ image_tag: ... --- --column 3 --header-lines 1 # <-- This variable uses the default delimiter
```

40
docs/shell_scripting.md
View file

@ -1,40 +0,0 @@
## Using it for shell scripting
For a real world scenario example, please check this [blog post](https://denisidoro.github.io/posts/cli-templates/).
Let's say you want to write a bash script that, among other things, asks the user to write the name of a git branch that should be checked out.
If you already have the [cheatsheet above](#cheatsheet-syntax), then you could write the following in your script:
```sh
navi --query "change branch" --best-match
```
**navi** will ask the user to fill all arguments needed.
If you want to set the `<branch>` beforehand in your script:
```sh
branch="master" navi --query "change branch" --best-match
```
- no interactive input will be shown
- the value for `<branch>` will be exactly the one passed as argument
If you want to filter some results for `<branch>`:
```sh
branch__query="master" navi --query "change branch" --best-match
```
- an interactive input will be shown, unless a single entry is autoselected
- the value for `<branch>` will be the one selected
If you want to select the best match for `<branch>`:
```sh
branch__best="master" navi --query "change branch" --best-match
```
- no interactive input will be shown
- the value for `<branch>` will be the one that best matches the one passed as argument

28
docs/usage/README.md Normal file
View file

@ -0,0 +1,28 @@
# The usage of Navi
Navi can be used in multiple ways
#### Defining the cheatsheets path at runtime
You can define the paths to use for cheatsheets at runtime using the `--path` parameter and a colon-separated paths list
For example, if we want to search for cheatsheets in `/some/dir` and in `/other/dir`:
```sh
navi --path '/some/dir:/other/dir'
```
## Logging
The log file will be created under the same directory where the configuration file is located.\
You can use the `RUST_LOG` environment variable to set the log level.
For example, to have the logging in debug mode when running navi:
```bash
RUST_LOG=debug navi
```
> [!NOTE]
> If the directory of the configuration file doesn't exist, no log file
> is going to be created.

66
docs/usage/commands/info/README.md Normal file
View file

@ -0,0 +1,66 @@
# The info subcommands of navi
Navi exposes information about its default values or examples for you to use.
<!-- TOC -->
* [The info subcommands of navi](#the-info-subcommands-of-navi)
* [Commands Reference](#commands-reference)
* [Default configuration information](#default-configuration-information)
* [Default configuration path](#default-configuration-path)
* [Example configuration file](#example-configuration-file)
* [Default cheatsheets path](#default-cheatsheets-path)
<!-- TOC -->
## Commands Reference
| Command | Description |
|---------------------|----------------------------------------------------|
| config-path | [DEPRECATED] Lets you see the default config path |
| cheats-path | [DEPRECATED] Lets you see the default cheats path |
| default-config-path | Lets you see the default config path |
| default-cheats-path | Lets you see the default cheats path |
| config-example | Lets you see an example for the configuration file |
| cheats-example | Lets you see an example for a cheat file |
## Default configuration information
### Default configuration path
Navi exposes its default configuration path with:
```sh
navi info config-path
```
> [!NOTE]
> See [/docs/configuration/](/docs/configuration/README.md#the-default-configuration-file-path) for more details on how the default configuration path is defined.
### Example configuration file
Navi lets you get an example configuration file with:
```sh
navi info config-example
```
> [!NOTE]
> You can retrieve this file at the following address: [/docs/examples/configuration/config-example.yaml](/docs/examples/configuration/config-example.yaml)
For example, you can use this command to create the default configuration file,
if not already present:
```sh
navi info config-example > "$(navi info config-path)"
```
## Default cheatsheets path
Navi exposes its default cheatsheets path with:
```sh
navi info cheats-path
```
> [!NOTE]
> See [/docs/configuration/](/docs/configuration/README.md#the-default-cheatsheets-path) for more details on how the cheatsheets path is defined.

48
docs/usage/commands/repo/README.md Normal file
View file

@ -0,0 +1,48 @@
# The repo subcommands of navi
<!-- TOC -->
* [The repo subcommands of navi](#the-repo-subcommands-of-navi)
* [Commands Reference](#commands-reference)
* [Browsing through cheatsheet repositories](#browsing-through-cheatsheet-repositories)
* [Importing cheatsheet repositories](#importing-cheatsheet-repositories)
<!-- TOC -->
## Commands Reference
| Command | Description |
|---------|-------------------------------------------------------------------|
| add | Lets you import a cheatsheet repository |
| browser | Lets you browse through a curated list of cheatsheet repositories |
## Browsing through cheatsheet repositories
Navi lets you browse featured [GitHub](https://github.com) repositories registered in [@denisidoro/cheats/featured_repos.txt](https://github.com/denisidoro/cheats/blob/master/featured_repos.txt).
You can find them within navi with the following command:
```sh
navi repo browse
```
## Importing cheatsheet repositories
You can import `cheatsheet repositories` using a working git-clone format.\
This includes using an HTTPS URL or an SSH URI.
- Import using HTTPS
```sh
navi repo add https://github.com/denisidoro/cheats
```
- Import using SSH
```shell
navi repo add git@github.com:denisidoro/cheats
```
> [!CAUTION]
> Despite `$NAVI_PATH` being set, it will not be used when installing cheat sheets directly via navi's own commands.\
> For example when running `navi add repo <repo>`, the default paths will still be used.
>
> To avoid this, you may simply clone repos via a regular `git clone` command, directly into `$NAVI_PATH`.

30
docs/usage/fzf-overrides/README.md Normal file
View file

@ -0,0 +1,30 @@
# The FZF Overrides of Navi
Navi allows you to override certain parts of FZF in multiple ways.
<!-- TOC -->
* [The FZF Overrides of Navi](#the-fzf-overrides-of-navi)
* [Command line arguments](#command-line-arguments)
* [Environment variables](#environment-variables)
<!-- TOC -->
## Command line arguments
Navi allows you to use command line arguments in order to override fzf values:
```sh
# if you want to override only when selecting snippets
navi --fzf-overrides '--height 3'
# if you want to override only when selecting argument values
navi --fzf-overrides-var '--height 3'
```
## Environment variables
Navi allows you to use environment variables in order to override fzf values.
```bash
# if you want to override for all cases
FZF_DEFAULT_OPTS="--height 3" navi
```

58
docs/usage/shell-scripting/README.md Normal file
View file

@ -0,0 +1,58 @@
# Navi and shell scripting
You can use Navi with shell scripting.
<!-- TOC -->
* [Navi and shell scripting](#navi-and-shell-scripting)
* [Simply calling a cheat](#simply-calling-a-cheat)
* [Defining variables while calling](#defining-variables-while-calling)
* [Filtering results for a variable](#filtering-results-for-a-variable)
* [Selecting the best match for a variable](#selecting-the-best-match-for-a-variable)
<!-- TOC -->
> [NOTE!]
> The following blog post gives you an example of a real world scenario: [denisidoro.github.io/posts/cli-templates/](https://denisidoro.github.io/posts/cli-templates/)
## Simply calling a cheat
Below is an example on how to call a cheat from within navi:
```sh
navi --query "change branch" --best-match
```
> [!NOTE]
> Navi will ask the user to fill all arguments/variables needed.
## Defining variables while calling
If you want to set the `<branch>` beforehand in your script, you can do as follows:
```sh
branch="master" navi --query "change branch" --best-match
```
Navi will not show any interactive input and `<branch>` will be exactly the one defined while calling.
## Filtering results for a variable
If you want to filter some results for `<branch>`, you can do as follows:
```sh
branch__query="master" navi --query "change branch" --best-match
```
Navi will show any interactive input, unless a single entry is automatically selected and
the value for `<branch>` will be the one selected by the user.
## Selecting the best match for a variable
If you want to select the best match for `<branch>`, you can do as follows:
```sh
branch__best="master" navi --query "change branch" --best-match
```
Navi will not show any interactive input, and the value for `<branch>` will be the one that
best matches the value passed as argument.

13
docs/vim.md
View file

@ -1,13 +0,0 @@
## vim
If you want syntax highlighting support for Navi in Vim, add those syntax rules
to your syntax files such as at `$VIMRUNTIME/syntax/navi.vim`.
The rules are defined based on the [Cheatsheet syntax](cheatsheet_syntax.md).
```vim
syntax match Comment "\v^;.*$"
syntax match Statement "\v^\%.*$"
syntax match Operator "\v^\#.*$"
syntax match String "\v\<.{-}\>"
syntax match String "\v^\$.*$"
```

71
docs/widgets/README.md Normal file
View file

@ -0,0 +1,71 @@
# Navi widgets
You want to launch Navi with a shortcut?\
Widgets are here for you!
Widgets are 3rd-party contributions and integrates Navi with 3rd-party software such as shells.
## List of shell widgets
| Shell | Navi support |
|------------|--------------------|
| Bash | :white_check_mark: |
| Fish | |
| Zsh | |
| NuShell | :white_check_mark: |
| PowerShell | :white_check_mark: |
## PowerShell Widget
- Removal
```powershell
Remove-Module navi.plugin
```
## Other widgets
- Tmux
- Vim
### Installing the shell widget
If you want to install it, add this line to your `.bashrc`-like file:
```sh
# bash
eval "$(navi widget bash)"
# zsh
eval "$(navi widget zsh)"
# fish
navi widget fish | source
# elvish
eval (navi widget elvish | slurp)
# xonsh
# xpip install xontrib-navi # ← run in your xonsh session to install xontrib
xontrib load navi # ← add to your xonsh run control file
```
#### Nushell
Due to Nushell's [unique design](https://www.nushell.sh/book/thinking_in_nu.html#think-of-nushell-as-a-compiled-language), it is not possible to `eval` a piece of code dynamically like in other shells therefore the integration process is a bit more involved. Here is an example:
1. run `^navi widget nushell | save ($nu.default-config-dir | path join "navi-integration.nu")`
2. add the following lines to `config.nu`:
```nushell
source ($nu.default-config-dir | path join "navi-integration.nu")
```
By default, `Ctrl+G` is assigned to launching **navi** (in xonsh can be customized with `$X_NAVI_KEY`, see [xontrib-navi](https://github.com/eugenesvk/xontrib-navi) for details).
There's currently no way to customize the widget behavior out-of-the-box. If you want to change the keybinding or the **navi** flags used by the widget, please:
1. run, e.g., `navi widget bash` in your terminal
2. copy the output
3. paste the output in your `.bashrc`-like file
4. edit the contents accordingly

86
docs/tmux.md → docs/widgets/howto/TMUX.md
View file

@ -1,37 +1,49 @@
## Tmux
You can use **navi** as a [Tmux](https://github.com/tmux/tmux/wiki) widget to reach your Vim commands, often used SQL queries, etc. in any command-line app even in SSH sessions.
Add these lines to your Tmux config file to access **navi** by pressing `prefix + C-g`.
```sh
bind-key -N "Open Navi (cheat sheets)" -T prefix C-g split-window \
"$SHELL --login -i -c 'navi --print | head -n 1 | tmux load-buffer -b tmp - ; tmux paste-buffer -p -t {last} -b tmp -d'"
```
Example cheatsheet:
```sh
% vim
# Quit without save
qa!
# Delete a paragraph
normal dap
# Generate sequence of numbers
put =range(<start>, <stop>)
% postgresql
# Describe table columns in `psql` or `pgcli`
select
table_name,
column_name,
data_type
from
information_schema.columns
where
table_name = '<table>';
```
# Tmux widget
You can use **navi** as a [Tmux](https://github.com/tmux/tmux/wiki) widget to reach your Vim commands,
often used SQL queries, etc. in any command-line app even in SSH sessions.
<!-- TOC -->
* [Tmux widget](#tmux-widget)
* [Keybinding navi](#keybinding-navi)
* [Example cheatsheet](#example-cheatsheet)
<!-- TOC -->
## Keybinding navi
To be able to open navi via <kbd> prefix + C-g </kbd>, you need to add the following lines
to your Tmux configuration file.
```sh
bind-key -N "Open Navi (cheat sheets)" -T prefix C-g split-window \
"$SHELL --login -i -c 'navi --print | head -n 1 | tmux load-buffer -b tmp - ; tmux paste-buffer -p -t {last} -b tmp -d'"
```
## Example cheatsheet
Here is an example cheatsheet to use inside Tmux:
```sh
% vim
# Quit without save
qa!
# Delete a paragraph
normal dap
# Generate sequence of numbers
put =range(<start>, <stop>)
% postgresql
# Describe table columns in `psql` or `pgcli`
select
table_name,
column_name,
data_type
from
information_schema.columns
where
table_name = '<table>';
```

23
docs/widgets/howto/VIM.md Normal file
View file

@ -0,0 +1,23 @@
# Vim widget
<!-- TOC -->
* [Vim widget](#vim-widget)
* [Syntax Highlighting](#syntax-highlighting)
<!-- TOC -->
## Syntax Highlighting
If you want syntax highlighting support for Navi in Vim, you need to
add those syntax rules to your syntax files such as at `$VIMRUNTIME/syntax/navi.vim`.
The rules are defined based on the [Cheatsheet syntax](/docs/cheatsheet/syntax/README.md).
Here is an example:
```vim
syntax match Comment "\v^;.*$"
syntax match Statement "\v^\%.*$"
syntax match Operator "\v^\#.*$"
syntax match String "\v\<.{-}\>"
syntax match String "\v^\$.*$"
```