mirror of
https://github.com/denisidoro/navi.git
synced 2026-07-22 17:47:56 +00:00
Improve README (#271)
This commit is contained in:
Denis Isidoro
GitHub
parent
07134996e4
commit
672fcc0c69
1 changed files with 90 additions and 109 deletions
199
README.md
199
README.md
|
|
@ -6,36 +6,34 @@ An interactive cheatsheet tool for the command-line.
|
|||
|
||||
|
||||
|
||||
**navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands, with argument values prompted to you. It uses [fzf](https://github.com/junegunn/fzf) under the hood.
|
||||
**navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands. Argument suggestions are prompted to you.
|
||||
|
||||
It can be either used as a command or as a shell widget (*à la* Ctrl-R).
|
||||
It uses [fzf](https://github.com/junegunn/fzf) under the hood and it can be either used as a command or as a shell widget (*à la* Ctrl-R).
|
||||
|
||||
Table of contents
|
||||
-----------------
|
||||
|
||||
* [Installation](#installation)
|
||||
* [Using Homebrew or Linuxbrew](#using-homebrew-or-linuxbrew)
|
||||
* [Using one-liner script](#using-one-liner-script)
|
||||
* [Using cargo](#using-cargo)
|
||||
* [Using install script](#using-install-script)
|
||||
* [Downloading pre-compiled binaries](#downloading-pre-compiled-binaries)
|
||||
* [Building from source](#building-from-source)
|
||||
* [Usage](#usage)
|
||||
* [Preventing execution](#preventing-execution)
|
||||
* [Pre-filtering](#pre-filtering)
|
||||
* [Shell widget](#shell-widget)
|
||||
* [More options](#more-options)
|
||||
* [Trying out online](#trying-out-online)
|
||||
* [Cheatsheets](#cheatsheets)
|
||||
* [Using your own custom cheatsheets](#using-your-own-custom-cheatsheets)
|
||||
* [Importing cheatsheets](#importing-cheatsheets)
|
||||
* [Adding your own cheatsheets](#adding-your-own-cheatsheets)
|
||||
* [Submitting cheatsheets](#submitting-cheatsheets)
|
||||
* [Cheatsheet syntax](#cheatsheet-syntax)
|
||||
* [Syntax overview](#syntax-overview)
|
||||
* [Variables](#variables)
|
||||
* [Advanced variable options](#advanced-variable-options)
|
||||
* [Variable dependency](#variable-dependency)
|
||||
* [Variable options](#variable-options)
|
||||
* [Table formatting](#table-formatting)
|
||||
* [Multiple choice](#multiple-choice)
|
||||
* [Multiline snippets](#multiline-snippets)
|
||||
* [List customization](#list-customization)
|
||||
* [Motivation](#motivation)
|
||||
* [Related projects](#related-projects)
|
||||
* [Etymology](#etymology)
|
||||
|
||||
|
|
@ -48,15 +46,24 @@ Installation
|
|||
brew install denisidoro/tools/navi
|
||||
```
|
||||
|
||||
Alternatively, you can use the official formula (but it will install a very old version of **navi**):
|
||||
Alternatively, you can use the official formula (but it will install a very old version):
|
||||
```sh
|
||||
brew install navi
|
||||
```
|
||||
|
||||
### Using one-liner script
|
||||
### Using [cargo](https://github.com/rust-lang/cargo)
|
||||
|
||||
```bash
|
||||
cargo install navi
|
||||
```
|
||||
|
||||
### Using install script
|
||||
|
||||
```bash
|
||||
bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)
|
||||
|
||||
# alternatively, to set directories:
|
||||
# SOURCE_DIR=/opt/navi BIN_DIR=/usr/local/bin bash <(curl -sL https://raw.githubusercontent.com/denisidoro/navi/master/scripts/install)l
|
||||
```
|
||||
|
||||
### Downloading pre-compiled binaries
|
||||
|
|
@ -68,27 +75,21 @@ You can download binaries [here](https://github.com/denisidoro/navi/releases/lat
|
|||
```bash
|
||||
git clone https://github.com/denisidoro/navi ~/.navi
|
||||
cd ~/.navi
|
||||
make install # or make SOURCE_DIR=/opt/navi BIN_DIR=/usr/local/bin install
|
||||
make install
|
||||
|
||||
# alternatively, to set install directory:
|
||||
# make BIN_DIR=/usr/local/bin install
|
||||
```
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
By simply running `navi` you will be prompted with the default cheatsheets.
|
||||
|
||||
### Preventing execution
|
||||
|
||||
If you run `navi --print`, the selected snippet won't be executed. It will be printed to stdout instead.
|
||||
|
||||
### Pre-filtering
|
||||
|
||||
If you run `navi query <cmd>`, the results will be pre-filtered.
|
||||
By running `navi` for the first time, you'll be suggested to download some cheatsheets. By running `navi` again, these cheatsheets will appear.
|
||||
|
||||
### Shell widget
|
||||
|
||||
You can use **navi** as a widget to your shell. This way, your history is correctly populated and you can edit the command as you wish before executing it.
|
||||
|
||||
In order to use it, add this line to your `.bashrc`-like file:
|
||||
You can use **navi** as a widget to your shell. This way, your history is correctly populated and you can edit the command as you wish before executing it. To set it up, add this line to your `.bashrc`-like file:
|
||||
```sh
|
||||
# bash
|
||||
source <(navi widget bash)
|
||||
|
|
@ -100,50 +101,44 @@ source <(navi widget zsh)
|
|||
navi widget fish | source
|
||||
```
|
||||
|
||||
By default, `Ctrl+G` is assigned to launching **navi**. If you want to change the keybinding, replace the argument of `bind` or `bindkey` in [the widget file](https://github.com/denisidoro/navi/search?q=filename%3Anavi.plugin.*&unscoped_q=filename%3Anavi.plugin.*).
|
||||
By default, `Ctrl+G` is assigned to launching **navi**.
|
||||
|
||||
### More options
|
||||
|
||||
Please refer to `navi --help` for more details.
|
||||
|
||||
|
||||
Trying out online
|
||||
--------------------
|
||||
|
||||
If you don't have access to bash at the moment and you want to live preview **navi**, head to [this playground](https://www.katacoda.com/denisidoro/scenarios/navi). It'll start a docker container with instructions for you to install and use the tool. Note: login required.
|
||||
If you don't have access to a Unix shell at the moment and you want to live preview **navi**, head to [this playground](https://www.katacoda.com/denisidoro/scenarios/navi). It'll start a docker container with instructions for you to install and use the tool. Note: login required.
|
||||
|
||||
|
||||
Cheatsheets
|
||||
-----------
|
||||
|
||||
### Using your own custom cheatsheets
|
||||
### Importing cheatsheets
|
||||
|
||||
In this case, you need to pass a `:`-separated list of separated directories which contain `.cheat` files:
|
||||
```sh
|
||||
navi --path "/folder/with/cheats"
|
||||
**navi** is able to import cheatsheets from git repositories:
|
||||
```
|
||||
navi repo add <path-to-a-git-repo-with-cheats> # example: navi repo add https://github.com/denisidoro/navi
|
||||
```
|
||||
|
||||
Alternatively, you can set an environment variable in your `.bashrc`-like file:
|
||||
```sh
|
||||
export NAVI_PATH="/folder/with/cheats:/another/folder"
|
||||
```
|
||||
### 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)`/navi`.
|
||||
|
||||
|
||||
### Submitting cheatsheets
|
||||
|
||||
Feel free to open a PR on https://github.com/denisidoro/cheats for me to include your contributions.
|
||||
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.
|
||||
|
||||
|
||||
Cheatsheet syntax
|
||||
-----------------
|
||||
|
||||
Cheatsheets are described in `.cheat` files.
|
||||
Cheatsheets are described in `.cheat` files that look like this:
|
||||
|
||||
### Syntax overview
|
||||
|
||||
- lines starting with `%` determine the start of a new cheatsheet and should contain tags;
|
||||
- lines starting with `#` should be descriptions of commands;
|
||||
- lines starting with `;` are ignored. You can use them for metacomments;
|
||||
- lines starting with `$` should contain commands that generate a list of possible values for a given argument;
|
||||
- all the other non-empty lines are considered as executable commands.
|
||||
|
||||
For example, this is a valid `.cheat` file:
|
||||
```sh
|
||||
% git, code
|
||||
|
||||
|
|
@ -153,8 +148,55 @@ git checkout <branch>
|
|||
$ branch: git branch | awk '{print $NF}'
|
||||
```
|
||||
|
||||
### Syntax overview
|
||||
|
||||
- lines starting with `%` determine the start of a new cheatsheet and should contain tags, useful for searching;
|
||||
- lines starting with `#` should be descriptions of commands;
|
||||
- lines starting with `;` are ignored. You can use them for metacomments;
|
||||
- lines starting with `$` should contain commands that generate a list of possible values for a given argument;
|
||||
- all the other non-empty lines are considered as executable commands.
|
||||
|
||||
It's irrelevant how many files are used to store cheatsheets. They can be all in a single file if you wish, as long as you split them accordingly with lines starting with `%`.
|
||||
|
||||
### 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.
|
||||
|
||||
### Advanced variable options
|
||||
|
||||
For lines starting with `$` you can add 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>
|
||||
|
||||
$ image_id: docker images --- --column 3 --header-lines 1 --delimiter '\s\s+'
|
||||
```
|
||||
|
||||
The supported parameters are:
|
||||
- `--allow-extra` *(experimental)*: handles `fzf` option `--print-query`. `enter` will prefer a selection and `tab` will prefer the query typed.
|
||||
- `--multi` : forwarded option to `fzf`.
|
||||
- `--header-lines` : forwarded option to `fzf`
|
||||
- `--column` : forwarded option to `fzf`.
|
||||
- `--delimiter` : forwarded option to `fzf`.
|
||||
|
||||
### Variable dependency
|
||||
|
||||
The command for generating possible inputs can refer previous variables:
|
||||
```sh
|
||||
# If you select 2 for x, the possible values of y will be 12 and 22
|
||||
echo <x> <y>
|
||||
|
||||
$ x: echo '1 2 3' | tr ' ' '\n'
|
||||
$ y: echo "$((x+10)) $((x+20))" | tr ' ' '\n'
|
||||
```
|
||||
|
||||
### Multiline snippets
|
||||
|
||||
Commands may be multiline:
|
||||
```sh
|
||||
# This will output "foo\nyes"
|
||||
|
|
@ -164,74 +206,12 @@ true \
|
|||
|| echo no
|
||||
```
|
||||
|
||||
### Variables
|
||||
|
||||
The interface prompts for variable names inside brackets (eg `<branch>`).
|
||||
|
||||
Variable names should only include alphanumeric characters and `_`.
|
||||
|
||||
### Variable dependency
|
||||
|
||||
The command for generating possible inputs can refer other variables:
|
||||
```sh
|
||||
# If you select 2 for x, the possible values of y will be 12 and 22
|
||||
echo <x> <y>
|
||||
|
||||
$ x: echo -e '1\n2\n3'
|
||||
$ y: echo -e "$((x+10))\n$((x+20))"
|
||||
```
|
||||
|
||||
### Variable options
|
||||
|
||||
For lines starting with `$` you can add use`---` to parse parameters to `fzf`.
|
||||
* `--allow-extra` *(experimental)*: handles `fzf` option `--print-query`. `enter` will prefer a selection,
|
||||
`tab` will prefer the query typed.
|
||||
* `--multi` : forwarded option to `fzf`.
|
||||
* `--header-lines` : forwarded option to `fzf`
|
||||
* `--column` : forwarded option to `fzf`.
|
||||
* `--delimiter` : forwarded option to `fzf`.
|
||||
|
||||
#### Table formatting
|
||||
|
||||
You can pick a specific column of a selection and set the number of lines considered as headers via `--column`, `--delimiter` and `--header-lines`:
|
||||
|
||||
```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+'
|
||||
```
|
||||
|
||||
#### Multiple choice
|
||||
|
||||
You can select multiple values via `--multi` and hitting `<TAB>`:
|
||||
|
||||
```sh
|
||||
# The resulting command will be something like: cat "a.txt" "b.txt"
|
||||
cat <files>
|
||||
|
||||
$ files: ls --- --multi
|
||||
```
|
||||
|
||||
List customization
|
||||
------------------
|
||||
|
||||
Lists can be stylized with the [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf) environment variable or `--fzf-overrides`. This way, you can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes), for example.
|
||||
Lists can be stylized with the [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf) environment variable or similar variables or parameters ( please refer to `navi --help`). This way, you can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes), for example.
|
||||
|
||||
Motivation
|
||||
----------
|
||||
|
||||
The main objectives are:
|
||||
- to increase discoverability, by finding snippets given keywords or descriptions;
|
||||
- to prevent you from running auxiliar commands, copying the result into the clipboard and then pasting into the original command;
|
||||
- to easily share one-liners with others so that they don't need to figure out how to write the commands;
|
||||
- to improve terminal usage as a whole.
|
||||
|
||||
Sure, you can find autocompleters out there for all your favorite commands. However, they are very specific and each one may offer a different learning curve.
|
||||
|
||||
Or you can launch a browser and search for instructions on Google, but that takes some time.
|
||||
|
||||
**navi**, on the other hand, intends to be a general purpose platform for bookmarking any snippet at a very low cost.
|
||||
|
||||
Related projects
|
||||
----------------
|
||||
|
|
@ -240,6 +220,7 @@ There are many similar projects out there ([bro](https://github.com/hubsmoke/bro
|
|||
|
||||
Most of them provide excellent cheatsheet repositories, but lack a nice UI and argument suggestions.
|
||||
|
||||
|
||||
Etymology
|
||||
---------
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue