Awesome
<div align="center">Navita: Navigate Smarter, Not Harder
Derived from "navigate" and "ita" (short for "iteration"), suggesting a tool that helps you navigate through iterations of directory visits.
Features • Dependencies • Installation • Environment Variables • Known Caveats • Concept/Motivation • Contributing to Navita • License
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.
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.
https://github.com/user-attachments/assets/c3e1e753-2c38-4c57-89ad-dcfca9cea85d
</div> <div align="center">Features
</div> <div align="center">Usual Directory Change
</div>Synopsis: cd [string...]
- 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.
- You can also navigate directories the same way you would with the usual built-in cd command.
<div align="center">[!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.<br>
Search & Traverse Child Directories
</div>Synopsis: cd (-s | --sub-search) [string...]
Recursively search subdirectories, excluding .git
and its subdirectories, and navigate to the selected one.
Search & Traverse Parent Directories
</div>Synopsis: cd (-S | --super-search) [string...]
<br>
cd .. 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.
<div align="center">Search & Traverse History
</div>Synopsis: cd -- [string...]
Search your recently visited directories and select the desired one. The current working directory will not be considered in the search.
<div align="center">[!NOTE] Visit a few directories after a clean or initial installation to build a history.
View History
</div>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.
Toggle Current & Previous Directories
</div>Synopsis: cd -
Switch between your current directory and the previous directory you were in. The previous directory is specific to the current shell.
<div align="center">Clean-up History
</div>Synopsis: cd (-c | --cleanup)
You can choose to either remove invalid paths from the history or clear the entire history. However, Navita will automatically remove non-existent and non-executable directories.
<div align="center">Version Information
</div>Synopsis: cd (-v | --version)
View Navita's version information.
<div align="center">Tab Completion
</div>- Navita supports Tab completion for its options and directories.
- 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
Path Exclusion for History
</div>- 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.
<div align="center">[!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.
Frecency Directory Ranking
</div>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.
<details> <summary>How it Works?</summary>$$ \text{Score} = \ln\left(\frac{F \times (T_2-T_1)}{T_2}+1\right) \times e^{\left(\frac{-k \times T_1}{T_2}\right)} $$
where:
F
is the frequency of access.T1
is the time difference between the most recent access and the current directory.T2
is the maximum time difference allowed (90 days default). CheckNAVITA_MAX_AGE
environment variable.k
controls the rate at which the weight of older accesses decreases. A higher value results in a faster decay rate. CheckNAVITA_DECAY_FACTOR
environment variable.- The logarithmic scaling reduces the impact of extremely high frequencies, ensuring a more balanced ranking.
- The exponential decay gradually reduces the importance of older accesses, prioritizing recent activity.
Aging
</div>- Directory paths are forgotten based on the following two conditions:
- Limit the maximum number of entries in the
$NAVITA_HISTORYFILE
file to 5000. - If a directory path's score falls to 0, an average score will be calculated. Directory paths with scores less than 20% of the average score will be removed.
- Limit the maximum number of entries in the
- These conditions will be checked once every 24 hours at shell startup.
- If a directory path is removed due to a score of 0, the remaining directory paths will have their frequencies adjusted according to the formula $\ln(F+1)$, where $F$ is the frequency of the particular directory path.
Additional Info
</div>- 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 theNAVITA_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.
Dependencies
</div>- 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)
Installation
</div>- Download the
navita.sh
file.
# using wget2
wget2 https://raw.githubusercontent.com/CodesOfRishi/navita/main/navita.sh
# or using curl
curl https://raw.githubusercontent.com/CodesOfRishi/navita/main/navita.sh --output navita.sh
- Source the
navita.sh
file in your.bashrc
/.zshrc
configuration file.
source "path/to/the/navita.sh"
<div align="center">
Environment Variables
</div>[!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
orY
to follow symbolic links.
-
NAVITA_RELATIVE_PARENT_PATH
- It 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
orN
to show the parent paths as absolute path.
- It defaults to
-
NAVITA_SHOW_AGE
- It defaults to
y
, i.e., show an age annotation next to the paths while searching and traversing from history. - Change it to
n
orN
, to not show an age annotation beside the paths.
- It defaults to
-
NAVITA_MAX_AGE
- Specifies maximum retention period for a directory path since last access.
- Navita determines the age of a directory based on its relative access time to the most recently accessed directory. If the most recent directory was accessed at time $a$ and another directory was accessed at time $(a+x)$, the age of the other directory is $x$ time units.
- The default value is
90
i.e., 90 days.
-
NAVITA_DECAY_FACTOR
- The rate at which the score of older accesses decreases. A higher value results in a faster decay rate.
- It defaults to
10
.
<div align="center">[!WARNING] The decay factor should always be positive. Only adjust the decay factor if you are confident in the algorithm's behavior with the new value.
Non-Configurable Environment Variables
</div>-
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
.
Known Caveats
</div>- Using suffix-exact-match FZF search syntax won't work in Search & Traverse History if
NAVITA_SHOW_AGE
environment variable is set toy
due to FZF Issue #3983.
Concept/Motivation
</div>- To address the tedium of the builtin
cd
command. - KISS&E - Keep It Simple, Straightforward & Efficient.
- No feature bloating.
Contributing to Navita
</div> <div align="center">Reporting Issues
</div>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.
<div align="center">License
</div>This project is licensed under the Apache License 2.0. See the LICENSE for details.