Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve documentation #395

Merged
merged 3 commits into from Aug 29, 2020
Merged

Improve documentation #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9c8a3e9
Improve documentation
denisidoro Aug 29, 2020
bdcdf54
Aug-29 18h52: cheatsheet_repositories.md, config.rs, README.md, ...
denisidoro Aug 29, 2020
e52fe75
Aug-29 18h56: README.md
denisidoro Aug 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
View file
Open in desktop
@@ -1,6 +1,6 @@
[package]
name = "navi"
version = "2.9.0"
version = "2.10.0"
authors = ["Denis Isidoro <denis_isidoro@live.com>"]
edition = "2018"
description = "An interactive cheatsheet tool for the command-line"
Expand Down
307 changes: 56 additions & 251 deletions README.md
View file
Open in desktop
Expand Up @@ -4,176 +4,63 @@ An interactive cheatsheet tool for the command-line and application launchers.

![Terminal demo](https://user-images.githubusercontent.com/3226564/76437136-ddc35900-6397-11ea-823c-d2da7615fe60.gif)

**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.
**navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands. Suggested values for arguments are dinamically displayed in a list.

#### Pros
- it will make you type less;
- it will spare you from knowing CLIs by heart;
- it will teach you new one-liners.
- it will make you type less
- it will spare you from knowing CLIs by heart
- 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).

![Alfred demo](https://user-images.githubusercontent.com/3226564/80294838-582b1b00-8743-11ea-9eb5-a335d8eed833.gif)

Table of contents
-----------------

* [Installation](#installation)
* [Using Homebrew or Linuxbrew](#using-homebrew-or-linuxbrew)
* [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)
* [Usage](#usage)
* [Shell widget](#shell-widget)
* [Alfred](#alfred)
* [More options](#more-options)
* [Trying out online](#trying-out-online)
* [Cheatsheets](#cheatsheets)
* [Importing cheatsheets](#importing-cheatsheets)
* [Adding your own cheatsheets](#adding-your-own-cheatsheets)
* [Submitting cheatsheets](#submitting-cheatsheets)
* [Cheatsheet repositories](#cheatsheet-repositories)
* [Cheatsheet syntax](#cheatsheet-syntax)
* [Syntax overview](#syntax-overview)
* [Variables](#variables)
* [Advanced variable options](#advanced-variable-options)
* [Variable dependency](#variable-dependency)
* [Multiline snippets](#multiline-snippets)
* [Variable as multiple arguments](#variable-as-multiple-arguments)
* [List customization](#list-customization)
* [Related projects](#related-projects)
* [Customization](#customization)
* [Using it for shell scripting](#using-it-for-shell-scripting)
* [More info](#more-info)
* [Trying out online](#trying-out-online)
* [Similar tools](#similar-tools)
* [Etymology](#etymology)

Installation
------------

### Using [Homebrew](http://brew.sh/) or [Linuxbrew](http://linuxbrew.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
```
**navi** can be installed with the following package managers:

### Using [nix](https://nixos.org/)
[![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
nix-env -iA nixpkgs.navi
```

### 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)
```

### Downloading pre-compiled binaries

You can download binaries [here](https://github.com/denisidoro/navi/releases/latest).

### Building from source

```bash
git clone https://github.com/denisidoro/navi ~/.navi
cd ~/.navi
make install

# alternatively, to set install directory:
# make BIN_DIR=/usr/local/bin install
brew install 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!
If `brew` isn't available, you can check [alternative install instructions](docs/installation.md).

Usage
-----

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. To set it up, add this line to your `.bashrc`-like file:
```sh
# bash
source <(echo "$(navi widget bash)")

# zsh
source <(echo "$(navi widget zsh)")

# fish
navi widget fish | source
```

By default, `Ctrl+G` is assigned to launching **navi**.

### Alfred

This is *experimental*. If you face any issues, please report the issue [here](https://github.com/denisidoro/navi/issues/348).

- make sure you have [Alfred Powerpack](https://www.alfredapp.com/powerpack/);
- make sure **navi** is up to date;
- make sure that the `navi` binary is in the `$PATH` determined by `~/.bashrc`;
- download and install the `.alfredworkflow` for the [latest release](https://github.com/denisidoro/navi/releases/latest).

### More options
There are 3 ways to use **navi**:

Please refer to `navi --help` for more details.
- by typing `navi` in the terminal and hitting \<Enter>
- by invoking it via a [shell widget](docs/installation.md#installing-the-shell-widget) in the terminal
- this way, the shell history is correctly populated (e.g. `docker run alpine` instead of `navi`) and you can edit the command as you wish before executing it
- as an [Alfred workflow](docs/alfred.md)

Cheatsheet repositories
-----------------------

Trying out online
--------------------

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.
Running **navi** for the first time will help you download and manage cheatsheets.


Cheatsheets
-----------

### Importing cheatsheets

You can find cheatsheet repositories with:
```sh
navi repo browse
```

In addition, you can import cheatsheets from any git repository:
```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.
You can also:
- [browse through featured cheatsheets](docs/cheatsheet_repositories.md#browsing-through-cheatsheet-repositories)
- [import cheatsheets from git repositories](docs/cheatsheet_repositories.md#importing-cheatsheets)
- [write your own cheatsheets](#cheatsheet-syntax) (and [share them](docs/cheatsheet_repositories.md#submitting-cheatsheets), if you want)
- [use cheatsheets from other tools](docs/cheatsheet_repositories.md#using-cheatsheets-from-other-tools), such as [tldr](https://github.com/tldr-pages/tldr) and [cheat.sh](https://github.com/chubin/cheat.sh)

Cheatsheet syntax
-----------------
Expand All @@ -189,136 +76,54 @@ 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](#variables);
- lines starting with `@` should contain [tags whose associated cheatsheet you want to base on](#extending-cheatsheets);
- all the other non-empty lines are considered as executable commands.
The full syntax and examples can be found [here](docs/cheatsheet_syntax.md).

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 `%`.
Customization
-------------

### Variables
You can:
- [change colors](docs/customization.md#changing-colors)
- [resize columns](docs/customization.md#changing-colors)
- [change how search is performed](docs/customization.md#overriding-fzf-options)

The interface prompts for variable names inside brackets (eg `<branch>`).
Using it for shell scripting
----------------------------

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 prefered. If you hit `<enter>` the selection will be prefered.

### 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:
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 write the following in your script:
```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 "[[ $0 == t* ]] && echo 1 || echo 0"
navi --query "git checkout" --best-match
```

The supported parameters are:
- `--prevent-extra` *(experimental)*: limits the user to select one of the suggestions;
- `--column <number>`: extracts a single column from the selected result;
- `--map <bash_code>` *(experimental)*: applies a map function to the selected variable value;

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:
If you want to set the `<branch>` beforehand in your script, you could then write:
```sh
# Should print /my/pictures/wallpapers
echo "<wallpaper_folder>"

$ pictures_folder: echo "/my/pictures"
$ wallpaper_folder: echo "<pictures_folder>/wallpapers"
branch="master" navi --query "git checkout" --best-match
```

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
More info
---------

Commands may be multiline:
Please run the following command to read more about all possible options:
```sh
# This will output "foo\nyes"
echo foo
true \
&& echo yes \
|| echo no
navi --help
```

### Variable as multiple arguments

```sh
# This will result into: cat "file1.json" "file2.json"
jsons=($(echo "<jsons>"))
cat "${jsons[@]}"

$ jsons: find . -iname '*.json' -type f -print --- --multi
```

List customization
------------------

Lists can be stylized with the [$FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#layout) environment variable or similar variables/parameters (please refer to `navi --help`). This way, you can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes), for example.
In addition, the [/docs](docs) folder includes more information.

Trying out online
-----------------

Related projects
----------------
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.

There are many similar projects out there ([bro](https://github.com/hubsmoke/bro), [eg](https://github.com/srsudar/eg), [cheat.sh](https://github.com/chubin/cheat.sh), [tldr](https://github.com/tldr-pages/tldr), [cmdmenu](https://github.com/amacfie/cmdmenu), [cheat](https://github.com/cheat/cheat), [beavr](https://github.com/denisidoro/beavr), [how2](https://github.com/santinic/how2) and [howdoi](https://github.com/gleitz/howdoi), to name a few).
Similar tools
-------------

Most of them provide excellent cheatsheet repositories, but lack a nice UI and argument suggestions.
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) 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
---------
Expand Down