{"id":15044998,"url":"https://github.com/codesofrishi/navita","last_synced_at":"2025-10-24T19:30:17.125Z","repository":{"id":257217522,"uuid":"836203461","full_name":"CodesOfRishi/navita","owner":"CodesOfRishi","description":"Navita is a Bash/Zsh utility for rapid directory traversal, employing fuzzy matching, history tracking, and path validation for efficient file system navigation.","archived":false,"fork":false,"pushed_at":"2024-09-26T18:18:54.000Z","size":301,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-09-26T23:20:10.734Z","etag":null,"topics":["bash","cd","command-line-tool","directory-traversal","linux","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodesOfRishi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-31T11:11:25.000Z","updated_at":"2024-09-26T15:32:33.000Z","dependencies_parsed_at":"2024-09-25T02:05:32.655Z","dependency_job_id":null,"html_url":"https://github.com/CodesOfRishi/navita","commit_stats":null,"previous_names":["codesofrishi/navita"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fnavita","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fnavita/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fnavita/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodesOfRishi%2Fnavita/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodesOfRishi","download_url":"https://codeload.github.com/CodesOfRishi/navita/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219874902,"owners_count":16554628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","cd","command-line-tool","directory-traversal","linux","zsh"],"created_at":"2024-09-24T20:51:19.866Z","updated_at":"2025-10-24T19:30:17.118Z","avatar_url":"https://github.com/CodesOfRishi.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Navita: Navigate Smarter, Not Harder\n\n_Derived from \"navigate\" and \"ita\" (short for \"iteration\"), suggesting a tool that helps you navigate through iterations of directory visits._\n\n[Features](#features) •\n[Dependencies](#dependencies) •\n[Installation](#installation) •\n[Environment Variables](#environment-variables) •\n[Concept/Motivation](#conceptmotivation) •\n[Contributing to Navita](#contributing-to-navita) •\n[License](#license)\n\n**Tired of typing out long, complex directory paths?** Navita is here to simplify your command-line experience! The powerful Bash tool uses fuzzy search to get you to your destination in seconds.\n\n**Forget about tedious typing.** You can instantly find and jump to any directory, no matter how deeply nested. Navita is a great tool for boosting your productivity and saving you valuable time.\n\n![navita-demo3](https://github.com/user-attachments/assets/66ac57f7-1e56-440f-b535-2d97b853e0ba)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e \n\n## Features \n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e \n\n### Usual Directory Change\n\n\u003c/div\u003e\n\n**Synopsis:** `cd [PCRE_EXPRESSION... | DIR]`\n\n- Navita will search the history and directly navigate to the highest-ranked matching directory. The current working directory will not be considered in the search.\n- For highest-ranked directory traversal, search strings will be matched using [Perl-compatible regular expressions (PCREs)](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) and are compared case-sensitively.\n- Navita has two exceptions when using PCREs, mainly to keep things (almost) compatible with FZF search syntax.\n    - The `.` character will be treated literally.\n    - The `!` character can be used to exclude matches for a specified search pattern or word.\n\n    ```bash\n    # For example, navigate to the highest-ranked directory path \n    # that does not contain the substring 'smartcd' \n    # and ends with the substring '.config'.\n    cd \\!smartcd .config\n    # OR\n    cd '!smartcd' .config\n    ```\n\n\u003e [!NOTE]\n\u003e Navita will compare the last word of the string argument to the end of the paths in the history to determine the highest-ranked matching directory.\n\u003e You can override this behaviour by explicitly specifying `$` (End-of-String Anchor) in your search string.\u003cbr\u003e \n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cb\u003eUseful PCRE search syntaxes↴\u003c/b\u003e\n\u003c/summary\u003e\u003cbr\u003e\n\n| Pattern               | Info                                     |\n| --------------------- | ---------------------------------------- |\n| `a`                   | The character `a`                        |\n| `ab`                  | The string `ab`                          |\n| \u003ccode\u003ea\u0026#124;b\u003c/code\u003e | `a` or `b`                               | \n| `a*`                  | 0 or more `a`'s                          |\n| `\\`                   | Escapes a special character              |\n| `*`                   | 0 or more                                |\n| `+`                   | 1 or more                                |\n| `?`                   | 0 or 1                                   |\n| `{2}`                 | Exactly 2                                |\n| `{2,5}`               | Between 2 and 5                          |\n| `{2,}`                | 2 or more                                |\n| `[ab-d]`              | One character of: `a`, `b`, `c`, `d`     |\n| `[^ab-d]`             | One character except: `a`, `b`, `c`, `d` |\n| `\\d`                  | One digit                                |\n| `\\D`                  | One non-digit                            |\n| `\\s`                  | One whitespace                           |\n| `\\S`                  | One non-whitespace                       |\n| `\\w`                  | One word character                       |\n| `\\W`                  | One non-word character                   |\n| `^`                   | Start of string                          |\n| `$`                   | End of string                            |\n| `\\b`                  | Word boundary                            |\n| `\\B`                  | Non-word boundary                        |\n| `[:alnum:]`           | Letters and digits                       |\n| `[:alpha:]`           | Letters                                  |\n| `[:digit:]`           | Decimal digits                           |\n| `[:ascii:]`           | Ascii codes 0 - 127                      |\n| `[:blank:]`           | Space or tab only                        |\n| `[:space:]`           | Whitespace                               |\n| `[:lower:]`           | Lowercase letters                        |\n| `[:upper:]`           | Uppercase letters                        |\n| `[:word:]`            | Word characters                          |\n\n\u003c/details\u003e\n\n- You can also navigate directories the same way you would with the usual built-in cd command.\n\n\u003cdiv align=\"center\"\u003e \n\n### Search \u0026 Traverse Child Directories\n\n\u003c/div\u003e\n\n**Synopsis:** `cd (-s | --sub-search) [STRING...]`\n\nRecursively search subdirectories, excluding `.git` and its subdirectories, and navigate to the selected one.\n\n\u003cdiv align=\"center\"\u003e \n\n### Search \u0026 Traverse Parent Directories\n\n\u003c/div\u003e\n\n\n**Synopsis:** `cd (-S | --super-search | ..) [STRING...]`\n\nSearch directories one level below the parent directories and navigate to the desired one. The current working directory will not be considered in the search.\n\n\u003cdiv align=\"center\"\u003e \n\n### Search \u0026 Traverse History\n\n\u003c/div\u003e\n\n**Synopsis:** `cd -- [STRING...]`\n\nSearch your recently visited directories and select the desired one. The current working directory will not be considered in the search.\n\n\u003e [!NOTE]\n\u003e Visit a few directories after a clean or initial installation to build a history.\n\n\u003cdiv align=\"center\"\u003e \n\n### View History\n\n\u003c/div\u003e\n\n**Synopsis:** `cd (-H | --history) [--by-time | --by-frequency | --by-score]`\n\nView Navita's history of visited directories. The history will be displayed in the `less` pager, or directly to STDOUT if it fits on a single screen. The output will be sorted based on the provided option:\n- `--by-time`: Sorts the history by access time, with the most recently accessed directories appearing first.\n- `--by-freq`: Sorts the history by frequency, showing the most frequently accessed directories first.\n- `--by-score`: Sorts the history by score, with the highest scoring directories at the top. This is the default option.\n\n\u003cdiv align=\"center\"\u003e \n\n### Toggle Current \u0026 Previous Directories\n\n\u003c/div\u003e\n\n**Synopsis:** `cd -`\n\nSwitch between your current directory and the previous directory you were in. The previous directory is specific to the current shell.\n\n\u003cdiv align=\"center\"\u003e \n\n### Clean-up History\n\n\u003c/div\u003e\n\n**Synopsis:** `cd (-c | --clean) [--invalid-paths | --ignored-paths | --custom-paths | --full-history]`\n\nYou can choose to either remove invalid paths or paths matching regex in the `$NAVITA_IGNOREFILE` file or custom paths from the history, or clear the entire history.\n\n\u003cdiv align=\"center\"\u003e \n\n### Version Information\n\n\u003c/div\u003e\n\n**Synopsis:** `cd (-v | --version)`\n\nView Navita's version information.\n\n\u003cdiv align=\"center\"\u003e\n\n### View Help\n\n\u003c/div\u003e\n\n**Synopsis:** `cd (-h | --help)`\n\nView help message.\n\n\u003cdiv align=\"center\"\u003e \n\n### Tab Completion\n\n\u003c/div\u003e\n\n- Navita supports Tab completion for its options, directories and Highest-ranked directory.\n    ```bash\n    # To trigger Highest-ranked directory completion, \n    # press the Tab key after entering a space following the last search term. \n    cd \\!smartcd .config\u003cSpace\u003e\u003cTab\u003e\n    ```\n- For Zsh, to initialize the completion system, the function `compinit` should be autoloaded, and then run simply as ‘`compinit`’. *Ref: [Zsh Completion System - Use of Compinit](https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Use-of-compinit)*\n\n\u003cdiv align=\"center\"\u003e \n\n### Path Exclusion for History\n\n\u003c/div\u003e\n\n- Prevent paths that match any regular expression pattern in the `$NAVITA_IGNOREFILE` file from being added to the history.\n- Navita automatically prevents the `.git` and `$HOME` directories from being added to the history by default.\n\n\u003e [!NOTE]\n\u003e Even if a path was part of the history prior to its inclusion in the `$NAVITA_IGNOREFILE` using a regular expression pattern, it will still be visible, but Navita will cease to boost its ranking.\n\n\u003cdiv align=\"center\"\u003e \n\n### Frecency Directory Ranking\n\n\u003c/div\u003e\n\nThe Frecency algorithm ranks directories based on a combination of two factors: \n- frequency (how often a directory is accessed) and, \n- recency (how recently it was accessed). \n\nThis ensures that the most relevant directories—those accessed both frequently and recently—are ranked higher, while directories with older access are deprioritized. \n\n\u003cdetails\u003e\n\u003csummary\u003eHow it Works?\u003c/summary\u003e \n\n$$ \\text{FrecencyScore(t)} =  \\ln\\Bigg(k + \\frac{10}{1+\\alpha_1(t-T_0)} + \\sum_{i=0}^{n} e^{-\\alpha_2(t-T_i)} \\Bigg) $$\n\nwhere,\n- `t` is the current time.\n- `T0` is the time of the most recent visit.\n- `Ti` represent the time of previous visits (with `i = 0` for the most recent visit and `i = n` for the oldest).\n- `k` is a constant (0.1) which provides a lower bound on the frecency score.\n- `α1` and `α2` are decay parameters:\n    - `α1 = 2 * 10^(-5)`, which controls the decay for the most recent visit.\n    - `α2 = 3 * 10^(-7)`, which controls the decay for all prior visits.\n\u003cbr\u003e\n\n- All times are expressed in seconds and the idea is to make recency more important than frequency.\n- **NOTE:** The Frecency algorithm was created by @homerours and is used in their [Jumper](https://github.com/homerours/jumper) project, another excellent fast file jumper. @homerours should be credited for the Frecency algorithm. \n- Detailed information about the algorithm can be found [here](https://github.com/homerours/jumper/blob/master/algorithm.md#frecency).\n\n\u003c/details\u003e\n\n\u003cdiv align=\"center\"\u003e \n\n### Aging\n\n\u003c/div\u003e\n\n- Navita will check aging once every 24 hours at shell startup.\n- During the aging process, Navita will,\n    - limit the entries in the history to 100 (default) most frecent directory paths,\n    - remove directory paths that match any pattern in the `$NAVITA_IGNOREFILE`, and\n    - remove invalid directory paths.\n\n\u003cdiv align=\"center\"\u003e \n\n### Additional Info\n\n\u003c/div\u003e\n\n- Frecency rankings are updated asynchronously at runtime.\n- Navita employs a locking mechanism to ensure atomic history updates, preventing race conditions that may arise from concurrent modifications.\n- For Navita to follow physical directory structures, use the `-P` option along with the other options. This will resolve symbolic links and navigate you to the actual physical location on disk. To make Navita *always* resolve symbolic links, check the [`NAVITA_FOLLOW_ACTUAL_PATH`](#environment-variables) environment variable.\n\n\u003e [!NOTE]\n\u003e If this option is used, it should be the very first option given to Navita.\n\n- Search syntax is same as the [FZF search syntax](https://junegunn.github.io/fzf/search-syntax/) except when searching for [Highest-ranked directory](#usual-directory-change). You can type in multiple search terms delimited by spaces. For example, FZF sees `^music .conf3$ sbtrkt !fire` as four separate search terms.\n\n    | Token      | Match Type                              | Description                                          |\n    | ---------- | --------------------------------------- | ---------------------------------------------------- |\n    | `sbtrkt`   | fuzzy-match                             | Items that include `sbtrkt` characters in that order |\n    | `'wild`    | exact-match (quoted)                    | Items that include `wild`                            |\n    | `'wild'`   | exact-boundary-match (quoted both ends) | Items that include `wild` at word boundaries         |\n    | `^music`   | prefix-exact-match                      | Items that start with `music`                        |\n    | `.conf3$`  | suffix-exact-match                      | Items that end with `.conf3`                         |\n    | `!fire`    | inverse-exact-match                     | Items that do not include `fire`                     |\n    | `!^music`  | inverse-prefix-exact-match              | Items that do not start with `music`                 |\n    | `!.conf3$` | inverrse-suffix-exact-match             | Items that do not end with `.conf3`                  | \n\n\u003cdiv align=\"center\"\u003e \n\n## Dependencies\n\n\u003c/div\u003e\n\n- [GNU Bash](http://tiswww.case.edu/php/chet/bash/bashtop.html) or [Zsh](https://www.zsh.org/)\n- [FZF](https://junegunn.github.io/fzf/)\n- [GNU Grep](https://www.gnu.org/software/grep/)\n- [GNU bc](https://www.gnu.org/software/bc/)\n- [GNU Find Utilities](https://www.gnu.org/software/findutils/) (basically the `find` command)\n- [Util-Linux](https://github.com/util-linux/util-linux) (basically the `flock` command)\n- [GNU Core Utilities](https://www.gnu.org/software/coreutils/)\n- [Less](http://www.greenwoodsoftware.com/less/) (only for viewing the history in a pager)\n\n\u003cdiv align=\"center\"\u003e \n\n## Installation\n\n\u003c/div\u003e\n\n1. Download the `navita.sh` file.\n\n```bash\n# using wget2\nwget2 https://raw.githubusercontent.com/CodesOfRishi/navita/main/navita.sh\n\n# or using curl\ncurl https://raw.githubusercontent.com/CodesOfRishi/navita/main/navita.sh --output navita.sh\n```\n\n2. Source the `navita.sh` file in your `.bashrc`/`.zshrc` configuration file.\n\n```bash\nsource \"path/to/the/navita.sh\"\n```\n\n\u003cdiv align=\"center\"\u003e \n\n## Environment Variables\n\n\u003c/div\u003e\n\n\u003e [!NOTE]\n\u003e If you want to keep your desired values rather than the default ones, make sure to export these environment variables *before* sourcing the `navita.sh` file in your `.bashrc`/`.zshrc`.\n\n- **NAVITA_DATA_DIR**\n    - Directory location for Navita's data files.\n    - Defaults to `$XDG_STATE_HOME/navita`\n    - If `XDG_STATE_HOME` is not set, it defaults to `~/.local/state/navita`.\n\n- **NAVITA_CONFIG_DIR**\n    - Directory location for Navita's configuration files.\n    - Defaults to `$XDG_CONFIG_HOME/navita`\n    - If `XDG_CONFIG_HOME`  is not set, it defaults to `~/.config/navita`.\n\n- **NAVITA_COMMAND**\n    - Name of the command to use Navita.\n    - Defaults to `cd`.\n\n- **NAVITA_FOLLOW_ACTUAL_PATH**\n    - Follow symbolic links and resolve them to their actual physical locations before making the directory change.\n    - Defaults to `n`, i.e., not to follow symbolic links.\n    - Change it to `y` or `Y` to follow symbolic links.\n\n- **NAVITA_RELATIVE_PARENT_PATH**\n    - Defaults to `y` i.e., show the resolved parent paths relative to the present working directory in [Search \u0026 Traverse Parent Directories](search--traverse-parent-directories) feature.\n    - Change it to `n` or `N` to show the parent paths as absolute path. \n\n- **NAVITA_SHOW_AGE**\n    - Defaults to `y`, i.e., show an age annotation next to the paths while searching and traversing from history.\n    - Change it to `n` or `N`, to not show an age annotation beside the paths.\n\n- **NAVITA_FZF_EXACT_MATCH**\n    - Defaults to `y`, i.e., Exact match and search in FZF when utilizing [Search \u0026 Traverse Child Directories](#search--traverse-child-directories), [Search \u0026 Traverse Parent Directories](#search--traverse-parent-directories) or [Search \u0026 Traverse History](#search--traverse-history).\n    - Change it to `n` or `N`, to Fuzzy match and search in FZF.\n    - It will not affect Tab completion in Bash or the [Highest-ranked directory search](#usual-directory-change).\n\n- **NAVITA_HISTORY_LIMIT**\n    - Maximum number of directory paths Navita should remember.\n    - Defaults to `100`.\n\n\u003cdiv align=\"center\"\u003e \n\n### Non-Configurable Environment Variables\n\n\u003c/div\u003e\n\n- **NAVITA_VERSION**\n    - Navita's version information.\n\n- **NAVITA_IGNOREFILE**\n    - The file containing regular expression patterns to ignore matching paths from being added to the history.\n    - The path to the file is `$NAVITA_CONFIG_DIR/navita-ignore`.\n\n- **NAVITA_HISTORYFILE**\n    - The file containing a history of directory paths visited using Navita, along with their associated metadata like frequency, access time, and score.\n    - The path to the file is `$NAVITA_DATA_DIR/navita-history`.\n\n\u003cdiv align=\"center\"\u003e \n\n## Concept/Motivation\n\n\u003c/div\u003e\n\n- To address the tedium of the builtin `cd` command.\n- KISS\u0026E - Keep It Simple, Straightforward \u0026 Efficient.\n- No feature bloating.\n\n\u003cdiv align=\"center\"\u003e \n\n## Contributing to Navita\n\n\u003c/div\u003e\n\nTo review the latest changes that have not yet been included in the latest release, check out the [dev](https://github.com/CodesOfRishi/navita/tree/dev) branch.\n\n\u003cdiv align=\"center\"\u003e \n\n### Reporting Issues\n\n\u003c/div\u003e\n\nIf you encounter any bugs or issues while using Navita, please open an issue on the Navita GitHub repository. Provide as much detail as possible, including steps to reproduce the issue and any relevant error messages.\n\n\u003cdiv align=\"center\"\u003e \n\n## License\n\n\u003c/div\u003e\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodesofrishi%2Fnavita","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodesofrishi%2Fnavita","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodesofrishi%2Fnavita/lists"}