Prettify md/yaml files

Resolved via `prettier -w .`
This commit is contained in:
Kian-Meng Ang 2022-09-08 20:56:04 +08:00
parent 9d862344e6
commit 5c6da68122
14 changed files with 147 additions and 136 deletions

View file

@ -1,10 +1,9 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
title: ""
labels: bug
assignees: ''
assignees: ""
---
**Describe the bug**
@ -12,6 +11,7 @@ A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
@ -24,6 +24,7 @@ A clear and concise description of what you expected to happen.
If applicable, add screenshots to help explain your problem.
**Versions:**
- OS: [e.g. macOS, WSL ubuntu, ubuntu]
- Shell Version [replace this text with the output of `sh --version`]

View file

@ -1,10 +1,9 @@
---
name: Feature request
about: Suggest an idea for this project
title: ''
title: ""
labels: new feature
assignees: ''
assignees: ""
---
**Is your feature request related to a problem? Please describe.**

View file

@ -3,10 +3,9 @@ name: Publish
on:
push:
tags:
- '*'
- "*"
jobs:
binary:
name: Publish ${{ matrix.target }}
runs-on: ${{ matrix.os }}

View file

@ -6,43 +6,42 @@ 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. Suggested values for arguments are dynamically displayed in a list.
#### Pros
## 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
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), [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).
Table of contents
-----------------
## Table of contents
* [Installation](#installation)
* [Usage](#usage)
* [Cheatsheet repositories](#cheatsheet-repositories)
* [Cheatsheet syntax](#cheatsheet-syntax)
* [Customization](#customization)
* [More info](#more-info)
* [Trying out online](#trying-out-online)
* [Similar tools](#similar-tools)
* [Etymology](#etymology)
- [Installation](#installation)
- [Usage](#usage)
- [Cheatsheet repositories](#cheatsheet-repositories)
- [Cheatsheet syntax](#cheatsheet-syntax)
- [Customization](#customization)
- [More info](#more-info)
- [Trying out online](#trying-out-online)
- [Similar tools](#similar-tools)
- [Etymology](#etymology)
Installation
------------
## 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).
Usage
-----
## Usage
There are multiple ways to use **navi**:
@ -56,20 +55,19 @@ There are multiple ways to use **navi**:
In particular, check [these instructions](https://github.com/denisidoro/navi/issues/491) if you want to replicate what's shown in the demo above.
Cheatsheet repositories
-----------------------
## Cheatsheet repositories
Running **navi** for the first time will help you download and manage cheatsheets.
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)
- [auto-update repositories](docs/cheatsheet_repositories.md#auto-updating-repositories)
Cheatsheet syntax
-----------------
## Cheatsheet syntax
Cheatsheets are described in `.cheat` files that look like this:
@ -84,40 +82,38 @@ $ branch: git branch | awk '{print $NF}'
The full syntax and examples can be found [here](docs/cheatsheet_syntax.md).
Customization
-------------
## Customization
You can:
- [setup your own config file](docs/config_file.md)
- [change colors](docs/customization.md#changing-colors)
- [resize columns](docs/customization.md#resizing-columns)
- [change how search is performed](docs/customization.md#overriding-fzf-options)
More info
---------
## More info
Please run the following command to read more about all possible options:
```sh
navi --help
```
In addition, please check the [/docs](docs) folder.
Trying out online
-----------------
## 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.
Similar tools
-------------
## 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) 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
---------
## 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.

View file

@ -1,7 +1,6 @@
Alfred
------
## Alfred
This is *experimental*. If you face any issues, please report [here](https://github.com/denisidoro/navi/issues/348).
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)
@ -11,7 +10,6 @@ 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/)

View file

@ -1,5 +1,4 @@
Aliases
----------------------------
## Aliases
**navi** doesn't have support for aliases as first-class citizens at the moment.

View file

@ -1,16 +1,16 @@
Cheatsheet repositories
-----------------------
## 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](#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
```
@ -18,6 +18,7 @@ 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
```
@ -37,11 +38,13 @@ In order to add your own repository as a featured cheatsheet repo, please [edit
![Demo](https://user-images.githubusercontent.com/3226564/91878474-bae27500-ec55-11ea-8b19-17876178e887.gif)
You can use cheatsheets from [tldr](https://github.com/tldr-pages/tldr) by running:
```sh
navi --tldr <query>
```
You can use cheatsheets from [cheat.sh](https://github.com/chubin/cheat.sh) by running:
```sh
navi --cheatsh <query>
```
@ -51,6 +54,7 @@ navi --cheatsh <query>
Right now, **navi** doesn't have support for auto-updating out of the box. However, you can achieve this by using `git` and `crontab`.
First make sure you cloned your repo using `git` to the correct folder:
```sh
user="<user>"
repo="<repo>"
@ -58,12 +62,14 @@ git clone "https://github.com/${user}/${repo}" "$(navi info cheats-path)/${user}
```
Then, add a cron job:
```sh
crontab -e
*/0 11 * * * bash -c 'cd "$(/usr/local/bin/navi info cheats-path)/<user>__<repo>" && /usr/local/bin/git pull -q origin master'
```
Please note the cron job above is just an example and you should edit it accordingly:
- In this example, the cron job is triggered every day at 11am. [crontab guru](https://crontab.guru/) may come in handy if you want to change this value
- The full paths to `navi` and `git` may differ in your setup. Check their actual values using `which navi` and `which git`
- Don't forget to replace `<user>__<repo>` with the actual folder name

View file

@ -1,13 +1,12 @@
Cheatsheet syntax
-----------------
## 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)
- [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)
### Syntax overview
@ -23,6 +22,7 @@ $ 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
@ -61,13 +61,15 @@ $ mapped: echo 'false true' | tr ' ' '\n' --- --map "grep -q t && echo 1 || echo
```
The supported parameters are:
- `--column <number>`: extracts a single column from the selected result
- `--map <bash_code>`: *(experimental)* applies a map function to the selected variable value
- `--prevent-extra`: *(experimental)* limits the user to select one of the suggestions
- `--fzf-overrides <arg>`: *(experimental)* applies arbitrary `fzf` overrides
- `--expand`: *(experimental)* converts each line into a separate argument
- `--map <bash_code>`: _(experimental)_ applies a map function to the selected variable value
- `--prevent-extra`: _(experimental)_ limits the user to select one of the suggestions
- `--fzf-overrides <arg>`: _(experimental)_ applies arbitrary `fzf` overrides
- `--expand`: _(experimental)_ converts each line into a separate argument
In addition, it's possible to forward the following parameters to `fzf`:
- `--multi`
- `--header-lines <number>`
- `--delimiter <regex>`
@ -80,6 +82,7 @@ In addition, it's possible to forward the following parameters to `fzf`:
### Variable dependency
The command for generating possible inputs can implicitly refer other variables by using the `<varname>` syntax:
```sh
# Should print /my/pictures/wallpapers
echo "<wallpaper_folder>"
@ -89,6 +92,7 @@ $ wallpaper_folder: echo "<pictures_folder>/wallpapers"
```
If you want to make dependencies explicit, you can use the `$varname` syntax:
```sh
# If you select "hello" for <x>, the possible values of <y> will be "hello foo" and "hello bar"
echo <x> <y>
@ -125,6 +129,7 @@ echo "<pictures_folder>/screenshots"
### Multiline snippets
Commands may be multiline:
```sh
# This will output "foo\nyes"
echo foo

View file

@ -1,13 +1,13 @@
Config file
-----------------
## Config file
* [Example](#example)
* [Location](#location)
* [Creating the file](#creating-the-file)
- [Example](#example)
- [Location](#location)
- [Creating the file](#creating-the-file)
### Example
An example config can be found by running:
```sh
navi info config-example
```
@ -17,6 +17,7 @@ You can also read it online by clicking [here](./config_file_example.yaml).
### Location
Run the following command to check where the config file is/should be located:
```sh
navi info config-path
```
@ -24,6 +25,7 @@ navi info config-path
### Creating the file
Run the following command to generate a config file with the default parameters:
```sh
navi info config-example > "$(navi info config-path)"
```

View file

@ -1,19 +1,18 @@
Customization
-------------
## Customization
* [Changing colors](#changing-colors)
* [Resizing columns](#resizing-columns)
* [Overriding fzf options](#overriding-fzf-options)
- [Changing colors](#changing-colors)
- [Resizing columns](#resizing-columns)
- [Overriding fzf options](#overriding-fzf-options)
### 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.
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.
You can change the column widths by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.
### Overriding fzf options
@ -38,4 +37,4 @@ export NAVI_FZF_OVERRIDES_VAR='--height 3'
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.
In addition, this can be set by properly configuring _navi_'s `config.yaml`. Please check `navi --help` for more instructions.

View file

@ -1,16 +1,15 @@
Installation
------------
## 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](#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
@ -49,6 +48,7 @@ For Windows user, using powershell
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:
@ -64,7 +64,6 @@ For Windows user, using powershell
Remark: Above example also adds custom colors for better readability in case you use standard blue for your Powershell
#### Using install script
```bash
@ -108,6 +107,7 @@ 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)"
@ -125,6 +125,7 @@ eval (navi widget elvish | slurp)
By default, `Ctrl+G` is assigned to launching **navi**.
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

View file

@ -1,11 +1,11 @@
Using it for shell scripting
----------------------------
## 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
```
@ -13,22 +13,28 @@ navi --query "change branch" --best-match
**navi** will ask the user to fill all arguments needed.
If you want to set the `<branch>` beforehand in your script:
```sh
branch="master" navi --query "change branch" --best-match
```
- no interactive input will be shown
- the value for `<branch>` will be exactly the one passed as argument
If you want to filter some results for `<branch>`:
```sh
branch__query="master" navi --query "change branch" --best-match
```
- an interactive input will be shown, unless a single entry is autoselected
- the value for `<branch>` will be the one selected
If you want to select the best match for `<branch>`:
```sh
branch__best="master" navi --query "change branch" --best-match
```
- no interactive input will be shown
- the value for `<branch>` will be the one that best matches the one passed as argument