Navita - Frecency based Directory Jumper

Synopsis: cd [PCRE_EXPRESSION... | DIR]

• 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.

• For highest-ranked directory traversal, search strings will be matched using Perl-compatible regular expressions (PCREs) and are compared case-sensitively.

• Navita has two exceptions when using PCREs, mainly to keep things (almost) compatible with FZF search syntax.

  • The . character will be treated literally.
  • The ! character can be used to exclude matches for a specified search pattern or word.

  # For example, navigate to the highest-ranked directory path 
  # that does not contain the substring 'smartcd' 
  # and ends with the substring '.config'.
  cd \!smartcd .config
  # OR
  cd '!smartcd' .config
  

[!NOTE] 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. You can override this behaviour by explicitly specifying $ (End-of-String Anchor) in your search string.

• You can also navigate directories the same way you would with the usual built-in cd command.

Synopsis: cd (-s | --sub-search) [STRING...]

Recursively search subdirectories, excluding .git and its subdirectories, and navigate to the selected one.

Synopsis: cd (-S | --super-search | ..) [STRING...]

Search directories one level below the parent directories and navigate to the desired one. The current working directory will not be considered in the search.

Synopsis: cd -- [STRING...]

Search your recently visited directories and select the desired one. The current working directory will not be considered in the search.

[!NOTE] Visit a few directories after a clean or initial installation to build a history.

Synopsis: cd (-H | --history) [--by-time | --by-frequency | --by-score]

View 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:

• --by-time: Sorts the history by access time, with the most recently accessed directories appearing first.
• --by-freq: Sorts the history by frequency, showing the most frequently accessed directories first.
• --by-score: Sorts the history by score, with the highest scoring directories at the top. This is the default option.

Synopsis: cd -

Switch between your current directory and the previous directory you were in. The previous directory is specific to the current shell.

Synopsis: cd (-c | --clean) [--invalid-paths | --ignored-paths | --custom-paths | --full-history]

You 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.

Synopsis: cd (-v | --version)

View Navita's version information.

Synopsis: cd (-h | --help)

View help message.

• Navita supports Tab completion for its options, directories and Highest-ranked directory.

  # To trigger Highest-ranked directory completion, 
  # press the Tab key after entering a space following the last search term. 
  cd \!smartcd .config<Space><Tab>
  

• 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

• Prevent paths that match any regular expression pattern in the $NAVITA_IGNOREFILE file from being added to the history.
• Navita automatically prevents the .git and $HOME directories from being added to the history by default.

[!NOTE] 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.

The Frecency algorithm ranks directories based on a combination of two factors:

• frequency (how often a directory is accessed) and,
• recency (how recently it was accessed).

This ensures that the most relevant directories—those accessed both frequently and recently—are ranked higher, while directories with older access are deprioritized.

• Navita will check aging once every 24 hours at shell startup.
• During the aging process, Navita will,
  • limit the entries in the history to 100 (default) most frecent directory paths,
  • remove directory paths that match any pattern in the $NAVITA_IGNOREFILE, and
  • remove invalid directory paths.

• Frecency rankings are updated asynchronously at runtime.
• 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 variable.

[!NOTE] If this option is used, it should be the very first option given to Navita.

• Search syntax is same as the FZF search syntax except when searching for Highest-ranked directory. You can type in multiple search terms delimited by spaces. For example, FZF sees ^music .conf3$ sbtrkt !fire as four separate search terms.

  Token	Match Type	Description
  sbtrkt	fuzzy-match	Items that include sbtrkt characters in that order
  'wild	exact-match (quoted)	Items that include wild
  'wild'	exact-boundary-match (quoted both ends)	Items that include wild at word boundaries
  ^music	prefix-exact-match	Items that start with music
  .conf3$	suffix-exact-match	Items that end with .conf3
  !fire	inverse-exact-match	Items that do not include fire
  !^music	inverse-prefix-exact-match	Items that do not start with music
  !.conf3$	inverrse-suffix-exact-match	Items that do not end with .conf3

• GNU Bash or Zsh
• FZF
• GNU Grep
• GNU bc
• GNU Find Utilities (basically the find command)
• GNU Core Utilities
• Less (only for viewing the history in a pager)

1. Download the navita.sh file.

wget2 https://raw.githubusercontent.com/CodesOfRishi/navita/main/navita.sh

curl https://raw.githubusercontent.com/CodesOfRishi/navita/main/navita.sh --output navita.sh

2. Source the navita.sh file in your .bashrc/.zshrc configuration file.

source "path/to/the/navita.sh"

[!NOTE] 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.

• NAVITA_DATA_DIR

  • Directory location for Navita's data files.
  • Defaults to $XDG_DATA_HOME/navita
  • If XDG_DATA_HOME is not set, it defaults to ~/.local/share/navita.

• NAVITA_CONFIG_DIR

  • Directory location for Navita's configuration files.
  • Defaults to $XDG_CONFIG_HOME/navita
  • If XDG_CONFIG_HOME is not set, it defaults to ~/.config/navita.

• NAVITA_COMMAND

  • Name of the command to use Navita.
  • Defaults to cd.

• NAVITA_FOLLOW_ACTUAL_PATH

  • Follow symbolic links and resolve them to their actual physical locations before making the directory change.
  • Defaults to n, i.e., not to follow symbolic links.
  • Change it to y or Y to follow symbolic links.

• NAVITA_RELATIVE_PARENT_PATH

  • Defaults to y i.e., show the resolved parent paths relative to the present working directory in Search & Traverse Parent Directories feature.
  • Change it to n or N to show the parent paths as absolute path.

• NAVITA_SHOW_AGE

  • Defaults to y, i.e., show an age annotation next to the paths while searching and traversing from history.
  • Change it to n or N, to not show an age annotation beside the paths.

• NAVITA_FZF_EXACT_MATCH

  • Defaults to y, i.e., Exact match and search in FZF when utilizing Search & Traverse Child Directories, Search & Traverse Parent Directories or Search & Traverse History.
  • Change it to n or N, to Fuzzy match and search in FZF.
  • It will not affect Tab completion in Bash or the Highest-ranked directory search.

• NAVITA_HISTORY_LIMIT

  • Maximum number of directory paths Navita should remember.
  • Defaults to 100.

• NAVITA_VERSION

  • Navita's version information.

• NAVITA_IGNOREFILE

  • The file containing regular expression patterns to ignore matching paths from being added to the history.
  • The path to the file is $NAVITA_CONFIG_DIR/navita-ignore.

• NAVITA_HISTORYFILE

  • The file containing a history of directory paths visited using Navita, along with their associated metadata like frequency, access time, and score.
  • The path to the file is $NAVITA_DATA_DIR/navita-history.

• Using suffix-exact-match FZF search syntax won't work in Search & Traverse History if NAVITA_SHOW_AGE environment variable is set to y due to FZF Issue #3983.

• To address the tedium of the builtin cd command.
• KISS&E - Keep It Simple, Straightforward & Efficient.
• No feature bloating.

To review the latest changes that have not yet been included in the latest release, check out the dev branch.

If 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.

This project is licensed under the Apache License 2.0. See the LICENSE for details.