A smarter cd command. Supports all major shells.
Go to file
2020-06-27 14:27:39 +05:30
.github/workflows Add windows-msvc cargo build target to GitHub Actions (#86) 2020-06-13 19:05:54 +05:30
src Rename $result to $_zoxide_result to avoid conflicts (#87) 2020-06-27 14:27:39 +05:30
.gitignore Add ranger plugin 2020-03-14 12:05:38 +05:30
build.rs Show commit hash in version number 2020-04-01 03:24:45 +05:30
Cargo.lock Release v0.4.1 2020-05-25 02:55:00 +05:30
Cargo.toml Release v0.4.1 2020-05-25 02:55:00 +05:30
CHANGELOG.md Release v0.4.1 2020-05-25 02:55:00 +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
ranger_zoxide.py Update ranger plugin 2020-04-08 01:36:15 +05:30
README.md Update badges 2020-06-23 14:55:41 +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: Installing zoxide

On Arch Linux Arch Linux

yay -S zoxide

On CentOS

dnf copr enable atim/zoxide
dnf install zoxide

On Fedora 32+ Fedora

dnf install zoxide

On FreeBSD FreeBSD

pkg install zoxide

On macOS / Linux (via Homebrew / Linuxbrew)

brew tap ajeetdsouza/zoxide
brew install zoxide

On macOS (via MacPorts) MacPorts

port install zoxide

On NixOS nixpkgs unstable

nix-env -iA nixpkgs.zoxide

Other (via Cargo) crates.io package

cargo install zoxide -f

Other (via precompiled binary) GitHub releases

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 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_MAXAGE: sets the maximum total rank after which entries start getting deleted