diff --git a/README.md b/README.md index 1fec742..460f914 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ An interactive cheatsheet tool for the command-line. - it will make you type less - it will teach you new one-liners -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). +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 @@ -29,17 +29,18 @@ It uses [fzf](https://github.com/junegunn/fzf), [skim](https://github.com/lotabo ## Installation -**navi** can be installed with the following package managers: - -[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions) - The recommended way to install **navi** is by running: ```sh brew install navi ``` -If `brew` isn't available, you can check [alternative install instructions](docs/installation.md). +> [!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: + +[![Packaging status](https://repology.org/badge/vertical-allrepos/navi.svg)](https://repology.org/project/navi/versions) ## Usage @@ -53,7 +54,6 @@ There are multiple ways to use **navi**: - pros: you can use your cheatsheets in any command-line app even in SSH sessions - as [aliases](docs/cheatsheet_syntax.md#aliases) - as a [shell scripting tool](docs/shell_scripting.md) -- as an [Alfred workflow](docs/alfred.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. @@ -103,17 +103,5 @@ Please run the following command to read more about all possible options: navi --help ``` -In addition, please check the [/docs](docs) folder. +In addition, please check the [/docs](docs) folder or the website. -## 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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2ddc246 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,41 @@ +# Navi icon [![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 + + +* [Navi icon ![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) + + +## 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. diff --git a/docs/cheatsheet/README.md b/docs/cheatsheet/README.md new file mode 100644 index 0000000..1e44720 --- /dev/null +++ b/docs/cheatsheet/README.md @@ -0,0 +1,64 @@ +# Navi cheatsheets + + +* [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) + + +## 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 | +|:------------------:|:--------------------------:| +| tab | The query is preferred | +| enter | The selection is preferred | + +It means if you enter the tab 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 +``` + +You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running: + +```sh +navi --cheatsh +``` diff --git a/docs/cheatsheet/getting-started/README.md b/docs/cheatsheet/getting-started/README.md new file mode 100644 index 0000000..f914b00 --- /dev/null +++ b/docs/cheatsheet/getting-started/README.md @@ -0,0 +1 @@ +# Cheatsheets - Getting started diff --git a/docs/cheatsheet/repositories/README.md b/docs/cheatsheet/repositories/README.md new file mode 100644 index 0000000..bf14c1d --- /dev/null +++ b/docs/cheatsheet/repositories/README.md @@ -0,0 +1,63 @@ +# 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 diff --git a/docs/cheatsheet/syntax/README.md b/docs/cheatsheet/syntax/README.md new file mode 100644 index 0000000..e83d8c7 --- /dev/null +++ b/docs/cheatsheet/syntax/README.md @@ -0,0 +1,248 @@ +# The syntax of a Navi cheatsheet + + +* [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) + + +## 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: 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.

:information_source: See [#variables](#variables) for more details. | +| Extended cheats | `@` | Lines starting with this character should contain tags associated to other defined cheats.

: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. ``).\ +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: 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: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo 0" + ``` + + +The supported parameters are: + +| Parameter | Description | +|:------------------------|:------------------------------------------------------------------------------------------| +| `--column ` | `` is the column number to extract from the result. | +| `--map ` | **_[EXPERIMENTAL]_** `` 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 ` | **_[EXPERIMENTAL]_** `` 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 ` | +| `--delimiter ` | +| `--query ` | +| `--filter ` | +| `--header ` | +| `--preview ` | +| `--preview-window ` | + +### 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. ``). + +Below is an example of using implicit dependencies to construct a path: + +```sh +# Should print /my/pictures/wallpapers +echo "" + +$ pictures_folder: echo "/my/pictures" +$ wallpaper_folder: echo "/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 , the possible values of will be "hello foo" and "hello bar" +echo + +# If you want to ignore the contents of and only print +: ; echo + +$ 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: 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 "/wallpapers" + +% screenshots +@ dirs, common + +# Should print /my/pictures/screenshots +echo "/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: 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 `:: `: + +```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'" +``` diff --git a/docs/cheatsheet_repositories.md b/docs/cheatsheet_repositories.md deleted file mode 100644 index dc60ac0..0000000 --- a/docs/cheatsheet_repositories.md +++ /dev/null @@ -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 -``` - -You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running: - -```sh -navi --cheatsh -``` - -### 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' -``` - -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 `__` with the actual folder name diff --git a/docs/cheatsheet_syntax.md b/docs/cheatsheet_syntax.md deleted file mode 100644 index 77f9240..0000000 --- a/docs/cheatsheet_syntax.md +++ /dev/null @@ -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: 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: git branch | awk '{print $NF}' -```` - -### Variables - -The interface prompts for variable names inside brackets (eg ``). - -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 `` the query typed will be preferred. If you hit `` 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 - -# Even though "false/true" is displayed, this will print "0/1" -echo - -$ 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 `: extracts a single column from the selected result -- `--map `: _(experimental)_ applies a map function to the selected variable value -- `--prevent-extra`: _(experimental)_ limits the user to select one of the suggestions -- `--fzf-overrides `: _(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 ` -- `--delimiter ` -- `--query ` -- `--filter ` -- `--header ` -- `--preview ` -- `--preview-window ` - -### Variable dependency - -The command for generating possible inputs can implicitly refer other variables by using the `` syntax: - -```sh -# Should print /my/pictures/wallpapers -echo "" - -$ pictures_folder: echo "/my/pictures" -$ wallpaper_folder: echo "/wallpapers" -``` - -If you want to make dependencies explicit, you can use the `$varname` syntax: - -```sh -# If you select "hello" for , the possible values of will be "hello foo" and "hello bar" -echo - -# If you want to ignore the contents of and only print -: ; echo - -$ 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 "/wallpapers" - -% screenshots -@ dirs, common - -# Should print /my/pictures/screenshots -echo "/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: 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 `:: `: - -```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'" -``` diff --git a/docs/configuration/README.md b/docs/configuration/README.md new file mode 100644 index 0000000..5e2560a --- /dev/null +++ b/docs/configuration/README.md @@ -0,0 +1,233 @@ +# 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: + + ![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: + 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. + diff --git a/docs/contributions/README.md b/docs/contributions/README.md new file mode 100644 index 0000000..6d14d7e --- /dev/null +++ b/docs/contributions/README.md @@ -0,0 +1,47 @@ +# 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. diff --git a/docs/contributions/bugs/README.md b/docs/contributions/bugs/README.md new file mode 100644 index 0000000..8e0b3ac --- /dev/null +++ b/docs/contributions/bugs/README.md @@ -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. diff --git a/docs/contributions/code/README.md b/docs/contributions/code/README.md new file mode 100644 index 0000000..628892f --- /dev/null +++ b/docs/contributions/code/README.md @@ -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). diff --git a/docs/contributions/documentation/README.md b/docs/contributions/documentation/README.md new file mode 100644 index 0000000..325873d --- /dev/null +++ b/docs/contributions/documentation/README.md @@ -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 +| | +-- +| +-- 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. + diff --git a/docs/alfred.md b/docs/deprecated/Alfred/README.md similarity index 75% rename from docs/alfred.md rename to docs/deprecated/Alfred/README.md index ea6e3ee..357c567 100644 --- a/docs/alfred.md +++ b/docs/deprecated/Alfred/README.md @@ -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/) diff --git a/docs/cheat_example.cheat b/docs/examples/cheatsheet/example.cheat similarity index 74% rename from docs/cheat_example.cheat rename to docs/examples/cheatsheet/example.cheat index 972e0d6..2b22f55 100644 --- a/docs/cheat_example.cheat +++ b/docs/examples/cheatsheet/example.cheat @@ -1,6 +1,6 @@ -% first cheat - -# print something -echo "My name is !" - -$ name: whoami \ No newline at end of file +% first cheat + +# print something +echo "My name is !" + +$ name: whoami diff --git a/docs/navi.cheat b/docs/examples/cheatsheet/navi.cheat similarity index 100% rename from docs/navi.cheat rename to docs/examples/cheatsheet/navi.cheat diff --git a/docs/config_file_example.yaml b/docs/examples/configuration/config-example.yaml similarity index 94% rename from docs/config_file_example.yaml rename to docs/examples/configuration/config-example.yaml index ae2706f..a96b494 100644 --- a/docs/config_file_example.yaml +++ b/docs/examples/configuration/config-example.yaml @@ -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 diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 72a8e64..0000000 --- a/docs/installation.md +++ /dev/null @@ -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 diff --git a/docs/installation/README.md b/docs/installation/README.md new file mode 100644 index 0000000..a3587a1 --- /dev/null +++ b/docs/installation/README.md @@ -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! diff --git a/docs/navi_config.md b/docs/navi_config.md index 4903a50..e69de29 100644 --- a/docs/navi_config.md +++ b/docs/navi_config.md @@ -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 `, 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: ### 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: ... --- --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 -``` diff --git a/docs/shell_scripting.md b/docs/shell_scripting.md deleted file mode 100644 index 5a90ec8..0000000 --- a/docs/shell_scripting.md +++ /dev/null @@ -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 `` beforehand in your script: - -```sh -branch="master" navi --query "change branch" --best-match -``` - -- no interactive input will be shown -- the value for `` will be exactly the one passed as argument - -If you want to filter some results for ``: - -```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 `` will be the one selected - -If you want to select the best match for ``: - -```sh -branch__best="master" navi --query "change branch" --best-match -``` - -- no interactive input will be shown -- the value for `` will be the one that best matches the one passed as argument diff --git a/docs/usage/README.md b/docs/usage/README.md new file mode 100644 index 0000000..0454406 --- /dev/null +++ b/docs/usage/README.md @@ -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. diff --git a/docs/usage/commands/info/README.md b/docs/usage/commands/info/README.md new file mode 100644 index 0000000..9fcdbbf --- /dev/null +++ b/docs/usage/commands/info/README.md @@ -0,0 +1,66 @@ +# The info subcommands of navi + +Navi exposes information about its default values or examples for you to use. + + +* [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) + + +## 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. + diff --git a/docs/usage/commands/repo/README.md b/docs/usage/commands/repo/README.md new file mode 100644 index 0000000..ce83054 --- /dev/null +++ b/docs/usage/commands/repo/README.md @@ -0,0 +1,48 @@ +# The repo subcommands of navi + + +* [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) + + +## 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 `, 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`. diff --git a/docs/usage/fzf-overrides/README.md b/docs/usage/fzf-overrides/README.md new file mode 100644 index 0000000..eecac45 --- /dev/null +++ b/docs/usage/fzf-overrides/README.md @@ -0,0 +1,30 @@ +# The FZF Overrides of Navi + +Navi allows you to override certain parts of FZF in multiple ways. + + +* [The FZF Overrides of Navi](#the-fzf-overrides-of-navi) + * [Command line arguments](#command-line-arguments) + * [Environment variables](#environment-variables) + + +## 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 +``` diff --git a/docs/usage/shell-scripting/README.md b/docs/usage/shell-scripting/README.md new file mode 100644 index 0000000..3eb8036 --- /dev/null +++ b/docs/usage/shell-scripting/README.md @@ -0,0 +1,58 @@ +# Navi and shell scripting + +You can use Navi with shell scripting. + + +* [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) + + +> [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 `` 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 `` will be exactly the one defined while calling. + +## Filtering results for a variable + +If you want to filter some results for ``, 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 `` will be the one selected by the user. + +## Selecting the best match for a variable + +If you want to select the best match for ``, 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 `` will be the one that +best matches the value passed as argument. diff --git a/docs/vim.md b/docs/vim.md deleted file mode 100644 index 70af1c9..0000000 --- a/docs/vim.md +++ /dev/null @@ -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^\$.*$" -``` diff --git a/docs/widgets/README.md b/docs/widgets/README.md new file mode 100644 index 0000000..fe58a2a --- /dev/null +++ b/docs/widgets/README.md @@ -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 diff --git a/docs/tmux.md b/docs/widgets/howto/TMUX.md similarity index 52% rename from docs/tmux.md rename to docs/widgets/howto/TMUX.md index 657561e..332c4db 100644 --- a/docs/tmux.md +++ b/docs/widgets/howto/TMUX.md @@ -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(, ) - -% postgresql - -# Describe table columns in `psql` or `pgcli` -select - table_name, - column_name, - data_type -from - information_schema.columns -where - table_name = ''; -``` +# 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. + + +* [Tmux widget](#tmux-widget) + * [Keybinding navi](#keybinding-navi) + * [Example cheatsheet](#example-cheatsheet) + + +## Keybinding navi + +To be able to open navi via prefix + C-g , 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(, ) + +% postgresql + +# Describe table columns in `psql` or `pgcli` +select + table_name, + column_name, + data_type +from + information_schema.columns +where + table_name = '
'; +``` diff --git a/docs/widgets/howto/VIM.md b/docs/widgets/howto/VIM.md new file mode 100644 index 0000000..fcfcc2c --- /dev/null +++ b/docs/widgets/howto/VIM.md @@ -0,0 +1,23 @@ +# Vim widget + + +* [Vim widget](#vim-widget) + * [Syntax Highlighting](#syntax-highlighting) + + +## 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^\$.*$" +``` diff --git a/src/commands/info.rs b/src/commands/info.rs index 6c600a7..def49c1 100644 --- a/src/commands/info.rs +++ b/src/commands/info.rs @@ -34,8 +34,13 @@ impl Runnable for Input { match info { // Here should be the example commands - Info::CheatsExample => println!("{}", include_str!("../../docs/cheat_example.cheat")), - Info::ConfigExample => println!("{}", include_str!("../../docs/config_file_example.yaml")), + Info::CheatsExample => { + println!("{}", include_str!("../../docs/examples/cheatsheet/example.cheat")) + } + Info::ConfigExample => println!( + "{}", + include_str!("../../docs/examples/configuration/config-example.yaml") + ), // Here should be the old deprecated default value commands Info::CheatsPath => println!("{}", &filesystem::default_cheat_pathbuf()?.to_string()), diff --git a/src/welcome.rs b/src/welcome.rs index 520f04f..8d9e722 100644 --- a/src/welcome.rs +++ b/src/welcome.rs @@ -3,7 +3,7 @@ use crate::prelude::*; use crate::structures::fetcher; pub fn populate_cheatsheet(parser: &mut Parser) -> Result<()> { - let cheatsheet = include_str!("../docs/navi.cheat"); + let cheatsheet = include_str!("../docs/examples/cheatsheet/navi.cheat"); let lines = cheatsheet.split('\n').map(|s| Ok(s.to_string())); parser.read_lines(lines, "welcome", None)?;