.github/workflows | ||
src | ||
.gitignore | ||
build.rs | ||
Cargo.lock | ||
Cargo.toml | ||
CHANGELOG.md | ||
demo.gif | ||
init.fish | ||
install.sh | ||
LICENSE | ||
ranger_zoxide.py | ||
README.md | ||
zoxide.plugin.zsh |
zoxide
A faster way to navigate your filesystem
Table of contents
Introduction
zoxide
is a blazing fast alternative to cd
, inspired by
z
and z.lua
.
It keeps track of the directories you use most frequently, and uses a ranking algorithm
to navigate to the best match.
Examples
z foo # cd to highest ranked directory matching foo
z foo bar # cd to highest ranked directory matching foo and bar
z foo/ # can also cd into actual directories
zi foo # cd with interactive selection using fzf
zq foo # echo the best match, don't cd
za /foo # add /foo to the database
zr /foo # remove /foo from the database
Getting started
Step 1: Installing zoxide
On Arch Linux
yay -S zoxide
On CentOS
dnf copr enable atim/zoxide
dnf install zoxide
On DragonFly BSD
pkg install zoxide
On Fedora 32+
dnf install zoxide
On FreeBSD
pkg install zoxide
On macOS / Linux (via Homebrew / Linuxbrew)
brew install zoxide
On macOS (via MacPorts)
port install zoxide
On NixOS
nix-env -iA nixpkgs.zoxide
On Void Linux
xbps-install -S zoxide
Other (via Cargo)
cargo install zoxide -f
Other (via precompiled binary)
Use the installation script:
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh | sh
Alternatively, you can also download a precompiled binary from the
releases page and add it to
your PATH
.
Step 2: Installing fzf
(optional)
If you want to use interactive fuzzy selection, you will also need to install
fzf
.
Step 3: Adding zoxide
to your shell
If you currently use z
, z.lua
, or zsh-z
, you may want to first import
your existing database into zoxide
:
zoxide import /path/to/db
bash
Add the following line to your ~/.bashrc
:
eval "$(zoxide init bash)"
fish
Add the following line to your ~/.config/fish/config.fish
:
zoxide init fish | source
POSIX shells
Add the following line to your shell's configuration file:
eval "$(zoxide init posix --hook prompt)"
The prompt
hook is recommended for POSIX shells because the default pwd
hook creates a temporary file for every session, which are only deleted upon
reboot. If you do want to use pwd
hooks instead, you may want to set up traps
to perform a cleanup once the shell exits:
trap '_zoxide_cleanup' EXIT HUP KILL TERM
trap '_zoxide_cleanup; trap - INT; kill -s INT "$$"' INT
trap '_zoxide_cleanup; trap - QUIT; kill -s QUIT "$$"' QUIT
NOTE: If you modify your PS1
at any point, you may need to re-run the above
command. This is due to the fact that the hook is stored in PS1
, in order to
be evaluated every time the prompt is displayed.
PowerShell
Add the following line to your profile:
Invoke-Expression (& {
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
(zoxide init --hook $hook powershell) -join "`n"
})
zsh
Add the following line to your ~/.zshrc
:
eval "$(zoxide init zsh)"
Configuration
init
flags
--cmd
: change thez
command (and corresponding aliases) to something else--hook <HOOK>
: change the event that adds a new entry to the database (default:pwd
)none
: never add entries (this will makezoxide
useless unless you manually configure a hook)prompt
: add an entry at every promptpwd
: add an entry whenever the current directory is changed
--no-aliases
: don't define extra aliases likezi
,zq
,za
, andzr
Environment variables
$_ZO_DATA_DIR
: directory wherezoxide
will store its data files (default: platform-specific; see thedirs
documentation for more information)$_ZO_ECHO
: when set to1
,z
will print the matched directory before navigating to it$_ZO_EXCLUDE_DIRS
: list of directories separated by platform-specific characters (":
" on Linux/macOS, ";
" on Windows) to be excluded from the database$_ZO_FZF_OPTS
: custom flags to pass tofzf
$_ZO_MAXAGE
: sets the maximum total age after which entries start getting deleted$_ZO_RESOLVE_SYMLINKS
: when set to1
,z add
will resolve symlinks.