A smarter cd command. Supports all major shells.
Go to file
2020-05-02 16:34:55 +05:30
.github/workflows add armv7 release step (#38) 2020-03-18 12:22:57 +05:30
src Add PWD hook for POSIX shells 2020-05-02 16:31:53 +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 Switch default hook to PWD. 2020-05-02 01:25:57 +05:30
Cargo.toml Canonicalize to regular paths instead of UNC paths on Windows 2020-04-10 00:13:16 +05:30
CHANGELOG.md Update CHANGELOG 2020-05-02 16:34:55 +05:30
init.fish * Add init subcommand for bash, fish, and zsh 2020-03-11 00:14:50 +05:30
install.sh Make install.sh executable 2020-03-08 08:37:11 +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 README 2020-04-05 20:45:59 +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 cd command that learns your habits

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

If you have Rust, this should be as simple as:

cargo install zoxide -f

Otherwise, try the install script:

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

If you want the interactive fuzzy selection feature, you will also need to install fzf.

Step 2: 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

zsh

Add the following line to your ~/.zshrc:

eval "$(zoxide init zsh)"

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

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

eval "$(zoxide init posix)"

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.

NOTE: PWD hooks are currently not supported for POSIX shells.

Configuration

init flags

  • --hook <HOOK>: change the event that adds a new entry to the database (default: prompt)
    • 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 you change directories
  • --no-define-aliases: don't define extra aliases like zi, zq, za, and zr
  • --z-cmd: rename the z command to something else

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: z will print the matched directory before navigating to it
  • $_ZO_EXCLUDE_DIRS: list of directories separated by platform-specific characters (":" on Linux and macOS, and ";" on Windows) to be excluded from the database
  • $_ZO_MAXAGE: sets the maximum total rank after which entries start getting deleted

Notes

If you recently updated zoxide from an older version to v0.3 and are seeing the following error:

Error: could not deserialize old database

Caused by:
    io error: failed to fill whole buffer

It is because v0.2 and v0.3 databases are incompatible. There is a script to automatically migrate your database to the new format, but it seems to be failing on some systems.

For a quick fix, you can try removing the old database file: rm ~/.zo