A smarter cd command. Supports all major shells.
Go to file
2020-10-31 13:45:29 +05:30
.github/workflows Run CI on Windows 2020-10-27 01:47:10 +05:30
contrib Add interactive query/remove and import 2020-10-27 00:11:40 +05:30
src Release v0.5.0 2020-10-31 00:22:09 +05:30
templates Add interactive query/remove and import 2020-10-27 00:11:40 +05:30
.gitignore Split crates 2020-10-18 14:52:13 +05:30
build.rs Split crates 2020-10-18 14:52:13 +05:30
Cargo.lock Release v0.5.0 2020-10-31 00:22:09 +05:30
Cargo.toml Release v0.5.0 2020-10-31 00:22:09 +05:30
CHANGELOG.md Release v0.5.0 2020-10-31 00:22:09 +05:30
demo.gif Add demo GIF to README 2020-05-30 05:08:30 +05:30
init.fish * Add init subcommand for bash, fish, and zsh 2020-03-11 00:14:50 +05:30
install.sh Release v0.4.1 2020-05-25 02:55:00 +05:30
LICENSE Initial commit 2020-03-05 20:06:58 +05:30
README.md Update installation instructions 2020-10-31 13:45:29 +05:30
zoxide.plugin.zsh * Add init subcommand for bash, fish, and zsh 2020-03-11 00:14:50 +05:30

zoxide

crates.io .github/workflows/release.yml

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.

demo

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: Install zoxide

zoxide works across all major platforms. If your distribution isn't included in the list below, you can directly install the binary from GitHub:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh | sh

If you would rather not run a script, you can download the binary from the Releases page and add it anywhere in your $PATH.

On Linux

Distribution Repository Instructions
Any crates.io cargo install zoxide
Any Linuxbrew brew install zoxide
Arch Linux AUR yay -Sy zoxide
CentOS Copr dnf copr enable atim/zoxide
dnf install zoxide
Debian Unstable Debian Packages apt install zoxide
Fedora Fedora Packages dnf install zoxide
NixOS nixpkgs nix-env -iA nixpkgs.zoxide
Void Linux Void Linux Packages xbps-install -S zoxide

On macOS

Repository Instructions
crates.io cargo install zoxide
Homebrew brew install zoxide
MacPorts port install zoxide

On Windows

Repository Instructions
crates.io cargo install zoxide
Scoop scoop install zoxide

On BSD

Distribution Repository Instructions
Any crates.io cargo install zoxide
DragonFly BSD DPorts pkg install zoxide
FreeBSD FreshPorts pkg install zoxide

Step 2: Install fzf (optional)

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. Installation instructions can be found here.

Step 3: Add 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

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"
})

xonsh

Add the following line to your profile (usually ~/.xonshrc):

execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')

zsh

Add the following line to your ~/.zshrc:

eval "$(zoxide init zsh)"

Any POSIX shell

Add the following line to your shell's configuration file:

eval "$(zoxide init posix --hook prompt)"

Configuration

init flags

  • --cmd: change the z 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 make zoxide useless unless you manually configure a hook)
    • prompt: add an entry at every prompt
    • pwd: add an entry whenever the current directory is changed
  • --no-aliases: don't define extra aliases like zi, zq, za, and zr

Environment variables

  • $_ZO_DATA_DIR: directory where zoxide will store its data files (default: platform-specific; see the dirs documentation for more information)
  • $_ZO_ECHO: when set to 1, 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 to fzf
  • $_ZO_MAXAGE: sets the maximum total age after which entries start getting deleted
  • $_ZO_RESOLVE_SYMLINKS: when set to 1, z add will resolve symlinks.