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.
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.
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.
.
character will be treated literally.!
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.
Pattern | Info |
---|---|
a |
The character a
|
ab |
The string ab
|
a|b |
a or b
|
a* |
0 or more a 's |
\ |
Escapes a special character |
* |
0 or more |
+ |
1 or more |
? |
0 or 1 |
{2} |
Exactly 2 |
{2,5} |
Between 2 and 5 |
{2,} |
2 or more |
[ab-d] |
One character of: a , b , c , d
|
[^ab-d] |
One character except: a , b , c , d
|
\d |
One digit |
\D |
One non-digit |
\s |
One whitespace |
\S |
One non-whitespace |
\w |
One word character |
\W |
One non-word character |
^ |
Start of string |
$ |
End of string |
\b |
Word boundary |
\B |
Non-word boundary |
[:alnum:] |
Letters and digits |
[:alpha:] |
Letters |
[:digit:] |
Decimal digits |
[:ascii:] |
Ascii codes 0 - 127 |
[:blank:] |
Space or tab only |
[:space:] |
Whitespace |
[:lower:] |
Lowercase letters |
[:upper:] |
Uppercase letters |
[:word:] |
Word characters |
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...]
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.
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 | --full-history]
You can choose to either remove invalid paths from the history or clear the entire history.
Synopsis: cd (-v | --version)
View Navita's version information.
# To trigger Highest-ranked directory completion,
# press the Tab key after entering a space following the last search term.
cd \!smartcd .config<Space><Tab>
compinit
should be autoloaded, and then run simply as ‘compinit
’. Ref: Zsh Completion System - Use of Compinit
$NAVITA_IGNOREFILE
file from being added to the history..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:
This ensures that the most relevant directories—those accessed both frequently and recently—are ranked higher, while directories with older access are deprioritized.
$$ \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). Check NAVITA_MAX_AGE
environment variable.k
controls the rate at which the weight of older accesses decreases. Check NAVITA_DECAY_FACTOR
environment variable.$NAVITA_HISTORYFILE
file to 5000.-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
|
find
command)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
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
$XDG_DATA_HOME/navita
XDG_DATA_HOME
is not set, it defaults to ~/.local/share/navita
.NAVITA_CONFIG_DIR
$XDG_CONFIG_HOME/navita
XDG_CONFIG_HOME
is not set, it defaults to ~/.config/navita
.NAVITA_COMMAND
cd
.NAVITA_FOLLOW_ACTUAL_PATH
n
, i.e., not to follow symbolic links.y
or Y
to follow symbolic links.NAVITA_RELATIVE_PARENT_PATH
y
i.e., show the resolved parent paths relative to the present working directory in Search & Traverse Parent Directories feature.n
or N
to show the parent paths as absolute path.NAVITA_SHOW_AGE
y
, i.e., show an age annotation next to the paths while searching and traversing from history.n
or N
, to not show an age annotation beside the paths.NAVITA_FZF_EXACT_MATCH
y
, i.e., Exact match and search in FZF when utilizing Search & Traverse Child Directories, Search & Traverse Parent Directories or Search & Traverse History.n
or N
, to Fuzzy match and search in FZF.NAVITA_MAX_AGE
90
i.e., 90 days.NAVITA_DECAY_FACTOR
10
.[!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.
NAVITA_VERSION
NAVITA_IGNOREFILE
$NAVITA_CONFIG_DIR/navita-ignore
.NAVITA_HISTORYFILE
$NAVITA_DATA_DIR/navita-history
.NAVITA_SHOW_AGE
environment variable is set to y
due to FZF Issue #3983.cd
command.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.