2020-03-07 21:04:47 +00:00
# zoxide
[![crates.io ](https://img.shields.io/crates/v/zoxide )](https://crates.io/crates/zoxide)
2020-03-10 18:32:40 +00:00
![.github/workflows/release.yml ](https://github.com/ajeetdsouza/zoxide/workflows/.github/workflows/release.yml/badge.svg )
2020-03-07 21:04:47 +00:00
A cd command that learns your habits
2020-03-08 18:27:24 +00:00
## Table of contents
2020-03-08 18:41:10 +00:00
- [Introduction ](#introduction )
2020-03-08 18:45:18 +00:00
- [Examples ](#examples )
2020-03-08 18:41:10 +00:00
- [Getting started ](#getting-started )
2020-03-11 10:36:51 +00:00
- [Installing `zoxide` ](#step-1-installing-zoxide )
- [Adding `zoxide` to your shell ](#step-2-adding-zoxide-to-your-shell )
2020-03-08 19:05:37 +00:00
- [zsh ](#zsh )
2020-03-10 18:32:40 +00:00
- [bash ](#bash )
2020-03-08 19:05:37 +00:00
- [fish ](#fish )
2020-03-29 21:54:37 +00:00
- [POSIX ](#posix )
2020-03-08 18:41:10 +00:00
- [Configuration ](#configuration )
2020-03-15 18:36:06 +00:00
- [`init` flags ](#init-flags )
2020-03-08 19:05:37 +00:00
- [Environment variables ](#environment-variables )
2020-03-07 21:04:47 +00:00
## Introduction
2020-03-17 16:21:42 +00:00
`zoxide` is a blazing fast alternative to `cd` , inspired by [`z` ](https://github.com/rupa/z ) and [`z.lua` ](https://github.com/skywind3000/z.lua ). It keeps track of the directories you use most frequently, and uses a ranking algorithm to navigate to the best match.
2020-03-08 03:22:48 +00:00
2020-03-07 21:04:47 +00:00
## Examples
```sh
2020-03-08 19:05:37 +00:00
z foo # cd to highest ranked directory matching foo
z foo bar # cd to highest ranked directory matching foo and bar
2020-03-07 21:04:47 +00:00
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
2020-03-08 19:12:09 +00:00
### Step 1: Installing `zoxide`
2020-03-07 21:04:47 +00:00
If you have Rust, this should be as simple as:
```sh
2020-03-10 23:44:44 +00:00
cargo install zoxide -f
2020-03-07 21:04:47 +00:00
```
Otherwise, try the install script:
```sh
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` ](https://github.com/junegunn/fzf.git ).
2020-03-08 19:12:09 +00:00
### Step 2: Adding `zoxide` to your shell
2020-03-07 21:04:47 +00:00
2020-03-27 13:55:37 +00:00
If you currently use `z` , `z.lua` , or `zsh-z` , you may want to first import your existing database into `zoxide` :
2020-03-15 18:36:06 +00:00
```sh
2020-03-27 13:55:37 +00:00
zoxide import /path/to/db
2020-03-15 18:36:06 +00:00
```
2020-03-10 19:53:49 +00:00
2020-03-07 21:04:47 +00:00
#### zsh
2020-03-10 18:32:40 +00:00
Add the following line to your `~/.zshrc` :
2020-03-07 21:04:47 +00:00
```sh
2020-03-10 18:32:40 +00:00
eval "$(zoxide init zsh)"
2020-03-07 21:04:47 +00:00
```
2020-03-10 18:32:40 +00:00
#### bash
2020-03-08 19:12:09 +00:00
2020-03-10 18:32:40 +00:00
Add the following line to your `~/.bashrc` :
2020-03-08 19:12:09 +00:00
```sh
2020-03-10 18:32:40 +00:00
eval "$(zoxide init bash)"
2020-03-08 19:12:09 +00:00
```
2020-03-08 12:29:43 +00:00
#### fish
2020-03-08 19:05:37 +00:00
2020-03-10 18:32:40 +00:00
Add the following line to your `~/.config/fish/config.fish` :
2020-03-08 19:05:37 +00:00
2020-03-08 16:15:06 +00:00
```sh
2020-03-10 18:32:40 +00:00
zoxide init fish | source
2020-03-08 16:15:06 +00:00
```
2020-03-29 21:54:37 +00:00
#### POSIX
Add the following line to your shell's configuration file (or, run it manually):
``` sh
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 we store our hook in `PS1` , in order to be evaluated every time the prompt is
displayed.
NOTE: There is no PWD hook provided for POSIX shells.
2020-03-07 21:04:47 +00:00
## Configuration
2020-03-15 18:36:06 +00:00
### `init` flags
- `--no-define-aliases` : don't define extra aliases like `zi` , `zq` , `za` , and `zr`
- `--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
2020-03-07 21:04:47 +00:00
### Environment variables
2020-03-15 18:36:06 +00:00
- `$_ZO_ECHO` : `z` will print the matched directory before navigating to it
2020-03-07 21:04:47 +00:00
- `$_ZO_DATA` : sets the location of the database (default: `~/.zo` )
- `$_ZO_MAXAGE` : sets the maximum total rank after which entries start getting deleted