diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 148 |
1 files changed, 117 insertions, 31 deletions
@@ -6,37 +6,91 @@ An interactive cheatsheet tool for the command-line so that you'll never say the — *Oh, it's not in my bash history*<br> — *Geez, it's almost what I wanted but I need to change some args* - + **navi** allows you to browse through cheatsheets (that you may write yourself or download from maintainers) and execute commands, prompting for argument values. -## Installation +Table of Contents +----------------- + + * [Installation](#installation) + * [Using Homebrew or Linuxbrew](#using-homebrew-or-linuxbrew) + * [Using git](#using-git) + * [Upgrading](#upgrading) + * [Usage](#usage) + * [Preventing execution](#preventing-execution) + * [Pre-filtering](#pre-filtering) + * [Searching online repositories](#searching-online-repositories) + * [More options](#more-options) + * [Trying out online](#trying-out-online) + * [Motivation](#motivation) + * [Cheatsheets](#cheatsheets) + * [Using your own custom cheatsheets](#using-your-own-custom-cheatsheets) + * [Submitting cheatsheets](#submitting-cheatsheets) + * [Cheatsheet syntax](#cheatsheet-syntax) + * [Syntax overview](#syntax-overview) + * [Variables](#variables) + * [FZF options](#fzf-options) + * [Related projects](#related-projects) + * [Etymology](#etymology) + +Installation +------------ + +### Using Homebrew or Linuxbrew + +You can use [Homebrew](http://brew.sh/) or [Linuxbrew](http://linuxbrew.sh/) +to install **navi**. + +### Using git + +Alternatively, you can `git clone` this repository and run `make`: -**Using [brew](https://brew.sh/):** ```sh -brew install denisidoro/tools/navi -``` - -**Without brew:** -```sh -git clone http://github.com/denisidoro/navi /opt/navi +git clone --depth 1 http://github.com/denisidoro/navi /opt/navi cd /opt/navi sudo make install # install fzf: https://github.com/junegunn/fzf ``` -## Usage +Upgrading +--------- -Simply call: -```sh -navi -``` +**navi** is being actively developed and you might want to upgrade it once in a while. Please follow the instruction below depending on the installation method used: + +- brew: `brew update; brew reinstall navi` +- git: `cd /opt/navi && sudo make update` + +Usage +----- + +By simply running `navi` you will be prompted with the default cheatsheets. + +### Preventing execution + +If you run `navi --print`, the selected command 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. + +### Searching online repositories + +If you run `navi search <cmd>`, **navi** will try to download cheatsheets from online repositories as well. + +Please note that these cheatsheets aren't curated by **navi**'s maintainers and should be taken with a grain of salt. If you're not sure about executing these commands, make sure to check the preview window or use the `--print` option. + +### More options + +Please refer to `navi --help` for more details. -## Trying it out online +Trying out online +-------------------- -Head to [this playground](https://www.katacoda.com/denisidoro/scenarios/navi) for previewing **navi**. +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. -## Motivation +Motivation +---------- The main objectives are: - to increase discoverability, by finding commands given keywords or descriptions; @@ -50,23 +104,31 @@ Or you can launch a browser and search for instructions on Google, but that take **navi**, on the other hand, intends to be a general purpose platform for bookmarking any command at a very low cost. -## Using your own cheatsheets +Cheatsheets +----------- -In this case, you need to pass the directory which contains `.cheat` files as in: +### Using your own custom cheatsheets + +In this case, you need to pass a `:`-separated list of separated directories which contain `.cheat`: ```sh -navi --dir "/folder/with/cheats" +navi --path "/folder/with/cheats" ``` Alternatively, you can set an environment variable in your `.bashrc`-like file: ```sh -export NAVI_DIR="/folder/with/cheats" +export NAVI_PATH="/folder/with/cheats:/another/folder" ``` -## Submitting cheatsheets +### Submitting cheatsheets Feel free to fork this project and open a PR for me to include your contributions. -## .cheat syntax +Cheatsheet syntax +----------------- + +Cheatsheets are describe in `.cheat` files. + +### Syntax overview - lines starting with `%` should contain tags which will be added to any command in a given file; - lines starting with `#` should be descriptions of commands; @@ -83,16 +145,40 @@ git checkout <branch> $ branch: git branch | awk '{print $NF}' ``` -For advanced usage, please refer to the files in [/cheats](https://github.com/denisidoro/navi/tree/master/cheats). +### Variables + +The interface prompts for variable names inside brackets (eg `<branch>`). + +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' | tr '\n' ' ' +$ y: echo "$((x+10))" "$((x+20))" | tr '\n' ' ' +``` + +### FZF options + +You can make pick a specific column of a selection and set the number of lines considered as headers: + +```sh +# This will pick the 3rd column and use the first line as header +docker rmi <image_id> + +$ image_id: docker images --- --headers 1 --column 3 +``` + +Related projects +---------------- + +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), [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). -## Alternatives +Most of them provide excellent cheatsheet repositories, but lack a nice UI. -- [cmdmenu](https://github.com/amacfie/cmdmenu); -- [denisidoro/beavr](https://github.com/denisidoro/beavr); -- [how2](https://github.com/santinic/how2); -- [howdoi](https://github.com/gleitz/howdoi); -- [cheat](https://github.com/cheat/cheat). +In any case, **navi** has the option to [search for some of these repositories](#installation). -## Etymology +Etymology +--------- In [The Legend of Zelda Ocarina of Time](https://zelda.gamepedia.com/Ocarina_of_Time), [navi](https://zelda.gamepedia.com/Navi) is a character that provides [Link](https://zelda.gamepedia.com/Link) with a variety of clues to help him solve puzzles and progress in his quest. |