Merge pull request #864 from denisidoro/tapyu-patch-1

Clearer explanation about .cheat file paths
denisidoro · Dec 10, 2023 · e1c2699 · e1c2699
2 parents a8f38db + 74ce5ad
commit e1c2699
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -59,7 +59,7 @@ In particular, check [these instructions](https://github.com/denisidoro/navi/iss
 
 ## Cheatsheet repositories
 
-Running **navi** for the first time will help you download and manage cheatsheets.
+Running **navi** for the first time will help you download and manage cheatsheets. By default, they are soted at `~/.local/share/navi/cheats/`.
 
 You can also:
 

diff --git a/docs/aliases.md b/docs/aliases.md
diff --git a/docs/cheatsheet_syntax.md b/docs/cheatsheet_syntax.md
@@ -7,6 +7,7 @@
 - [Variable dependency](#variable-dependency)
 - [Multiline snippets](#multiline-snippets)
 - [Variable as multiple arguments](#variable-as-multiple-arguments)
+- [Aliases](#aliases)
 
 ### Syntax overview
 
@@ -31,10 +32,6 @@ Lines starting with:
 
 All the other non-empty lines are considered as executable commands.
 
-### Folder structure
-
-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>`).
@@ -146,3 +143,42 @@ cat <jsons>
 
 $ 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 `:: <some_alias>`:
+
+```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/navi_config.md b/docs/navi_config.md
@@ -0,0 +1,32 @@
+## 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`. The command
+```sh
+navi info config-path
+```
+prints which config file path is being used. You can get an config file example by running
+```sh
+navi info config-example
+```
+or by clicking [here](./config_file_example.yaml). To turn this example your config file, 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 that paths defined in its config files. 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-separed 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 `%`.