repository·main·Indexed 13 days ago
https://github.com/ajeetdsouza/zoxideA smarter cd command for your terminal that learns your habits and tracks frequently visited directories to enable fast navigation via fuzzy matching. Compatible with all major shells, zoxide version 0.10.0 supports interactive selection via fzf and provides subcommands for database management including add, import, query, and remove.
cd command inspired by z and autojump. It tracks the directories you visit most frequently, allowing you to "jump" to them using just a few keystrokes. It is compatible with all major shells.clap library. Note that because clap is currently in beta, these completions should be treated as unstable and may change in future versions.zoxide integrates with many applications. Some are natively supported, while others require specific plugins.
aercfelix, joshuto, rfm, yazisesh, tmux-session-wizard, tmux-sessionxzabb, zesh, zsh-autocompletealfred (via alfred-zoxide), raycast (via raycast-zoxide)emacs (via zoxide.el), vim / neovim (via zoxide.vim), telescope.nvim (via telescope-zoxide)lf (see wiki), nnn (via nnn-autojump), ranger (via ranger-zoxide), xplr (via zoxide.xplr)clink (via clink-zoxide)xxh (via xxh-plugin-prerun-zoxide)You can install the zoxide binary using a package manager or a shell script depending on your platform.
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | shcargo install zoxide --locked (crates.io)conda install -c conda-forge zoxide (conda-forge)brew install zoxide (Linuxbrew)nix-env -iA nixpkgs.zoxide (nixpkgs)apk add zoxide (Alpine Linux 3.13+)pacman -S zoxide (Arch Linux, Manjaro)dnf install zoxide (Fedora 32+)emerge app-shells/zoxide (Gentoo)zypper install zoxide (openSUSE Tumbleweed)pacstall -I zoxide-deb (Rhino Linux)eopkg install zoxide (Solus)xbps-install -S zoxide (Void Linux)cargo install zoxide --locked (crates.io)brew install zoxide (Homebrew)conda install -c conda-forge zoxide (conda-forge)port install zoxide (MacPorts)nix-env -iA nixpkgs.zoxide (nixpkgs)curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | shwinget install ajeetdsouza.zoxidecargo install zoxide --locked (crates.io)choco install zoxide (Chocolatey)conda install -c conda-forge zoxide (conda-forge)scoop install zoxide (Scoop)curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | shcargo install zoxide --locked (crates.io)pkg install zoxide (DragonFly BSD, FreeBSD)pkgin install zoxide (NetBSD)curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bashpkg install zoxidecurl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bashcurl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh_ZO_EXCLUDE_DIRS environment variable. This is the preferred method for managing directory exclusion rather than using zoxide remove for individual entries.zoxide uses two main concepts to rank directories: Frecency and Aging.
Frecency is a combination of frequency and recency. Every time a directory is accessed, its score increases. The score is then weighted based on how recently it was accessed:
score * 4score * 2score / 2score / 4The aging algorithm limits the database size using the _ZO_MAXAGE parameter (default 10000). If the total frecency of all directories exceeds _ZO_MAXAGE, zoxide divides each directory's score by a factor k until the total is approximately 90% of _ZO_MAXAGE. Any directory whose score falls below 1 is removed.
When using the --interactive flag, zoxide spawns fzf.
If you have the FZF_DEFAULT_OPTS environment variable set in your configuration, zoxide will use those options. Otherwise, it defaults to a specific set of arguments designed for a smooth terminal experience:
--exact
--no-sort
--bind=ctrl-z:ignore,btab:up,tab:down
--cycle
--keep-right
--border=sharp
--height=45%
--info=inline
--layout=reverse
--tabstop=1
--exit-0Note that zoxide also enables fzf preview mode by default.
To use zoxide, you must generate and evaluate its shell configuration. The command zoxide init <SHELL> produces the necessary script for your specific shell environment. Follow the instructions below for your shell to add the initialization to your configuration file.
# Example for Bash
eval "$(zoxide init bash)"To use zoxide effectively, you must generate and source its shell configuration. Use the zoxide-init subcommand to generate the necessary configuration for your specific shell.
Note: Any environment variables used for configuration (like _ZO_DATA_DIR or _ZO_ECHO) must be set before calling zoxide-init.
# Example of how you would typically use it in a shell config (e.g., .bashrc or .zshrc)
eval "$(zoxide init bash)"Depending on your shell, add the following lines to the end of your configuration file:
File: ~/.bashrc
eval "$(zoxide init bash)"File: ~/.elvish/rc.elv (Requires elvish v0.18.0+)
eval $(zoxide init elvish | slurp)File: ~/.config/fish/config.fish
zoxide init fish | sourceFile: Your env file (find via $nu.env-path) and your config file (find via $nu.config-path). Requires Nushell v0.89.0+
# In your env file:
zoxide init nushell | save -f ~/.zoxide.nu
# In your config file:
source ~/.zoxide.nuFile: Your profile (find via echo $profile)
Invoke-Expression (& { (zoxide init powershell | Out-String) })File: ~/.tcshrc
zoxide init tcsh > ~/.zoxide.tcsh
source ~/.zoxide.tcshFile: ~/.xonshrc
execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')File: ~/.zshrc
eval "$(zoxide init zsh)"eval "$(zoxide init posix --hook prompt)"zoxide provides a smarter cd command that uses a ranking algorithm to navigate to frequently used directories. You can use the z command to jump to directories matching specific patterns.
Common usage patterns:
z <pattern>: Jump to the highest ranked directory matching the pattern.z <pattern1> <pattern2>: Jump to the highest ranked directory matching both patterns.z <pattern> /: Jump to a subdirectory starting with the pattern.z <path>: Works like a regular cd command (absolute or relative paths).z ..: Go up one level.z -: Go to the previous directory.zi <pattern>: Interactive selection using fzf to choose from matches.z foo # cd into highest ranked directory matching foo
z foo bar # cd into highest ranked directory matching foo and bar
z foo / # cd into a subdirectory starting with foo
z ~/foo # works like a regular cd command
z .. # cd one level up
z - # cd into previous directory
zi foo # cd with interactive selection (requires fzf)The zoxide import command allows you to migrate directory history from other jump tools into the zoxide database.
Supported Formats:
autojump: Imports paths from Autojump. Note that zoxide only imports the paths, not the scores, because the matching algorithms differ.z: Used for fasd, z, z.lua, or zsh-z databases.Behavior and Merging:
zoxide database is not empty.zoxide history instead of replacing it, use the --merge flag.zoxide import PATH --from FORMAT [OPTIONS]
# Example: Merging autojump data
zoxide import ~/.autojump_history --from autojump --merge