zoxide/README.md

96 lines
2.7 KiB
Markdown
Raw Normal View History

2020-03-07 21:04:47 +00:00
# zoxide
[![crates.io](https://img.shields.io/crates/v/zoxide)](https://crates.io/crates/zoxide)
![.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-08 19:05:37 +00:00
- [Installing `zoxide`](#installing-zoxide)
- [Adding `zoxide` to your shell](#adding-zoxide-to-your-shell)
- [zsh](#zsh)
- [bash](#bash)
2020-03-08 19:05:37 +00:00
- [fish](#fish)
2020-03-08 18:41:10 +00:00
- [Configuration](#configuration)
2020-03-08 19:05:37 +00:00
- [Environment variables](#environment-variables)
2020-03-07 21:04:47 +00:00
## Introduction
`zoxide` is a new `cd` alternative 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
On my system, compiled with the `x86_64-unknown-linux-musl` target, `hyperfine` reports that `zoxide` runs 10-20x faster than `z.lua`, which, in turn, runs 3x faster than `z`. This is pretty significant, since this command runs once at every shell prompt, and any slowdown there will result in an increased loading time for every prompt.
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
cargo install zoxide
```
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
By default, `zoxide` defines the `z`, `zi`, `za`, `zq`, and `zr` aliases. If you'd like to go with just the barebones `z`, pass the `--no-define-aliases` flag to `zoxide init`.
2020-03-07 21:04:47 +00:00
#### zsh
Add the following line to your `~/.zshrc`:
2020-03-07 21:04:47 +00:00
```sh
eval "$(zoxide init zsh)"
2020-03-07 21:04:47 +00:00
```
#### bash
2020-03-08 19:12:09 +00:00
Add the following line to your `~/.bashrc`:
2020-03-08 19:12:09 +00:00
```sh
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
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
zoxide init fish | source
2020-03-08 16:15:06 +00:00
```
2020-03-07 21:04:47 +00:00
## Configuration
### Environment variables
- `$_ZO_DATA`: sets the location of the database (default: `~/.zo`)
- `$_ZO_MAXAGE`: sets the maximum total rank after which entries start getting deleted