zoxide/README.md

156 lines
4.3 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-05-03 12:41:35 +00:00
A faster way to navigate your filesystem
2020-03-07 21:04:47 +00:00
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)
- [bash](#bash)
2020-03-08 19:05:37 +00:00
- [fish](#fish)
2020-05-03 12:41:35 +00:00
- [POSIX](#posix-shells)
2020-05-06 06:03:06 +00:00
- [PowerShell](#powershell)
2020-05-03 12:41:35 +00:00
- [zsh](#zsh)
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-29 23:55:56 +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
```
2020-03-29 23:55:56 +00:00
If you want the interactive fuzzy selection feature, you will also need to install
[`fzf`](https://github.com/junegunn/fzf.git).
2020-03-07 21:04:47 +00:00
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-29 23:55:56 +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
```
#### 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-05-03 12:41:35 +00:00
#### POSIX shells
2020-03-29 23:55:56 +00:00
Add the following line to your shell's configuration file:
2020-03-29 23:55:56 +00:00
```sh
2020-05-03 12:41:35 +00:00
eval "$(zoxide init posix --hook prompt)"
```
2020-05-03 12:41:35 +00:00
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:
2020-05-03 12:41:35 +00:00
```sh
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.
#### zsh
Add the following line to your `~/.zshrc`:
```sh
eval "$(zoxide init zsh)"
```
2020-05-06 06:03:06 +00:00
#### PowerShell
Add the following line to your profile:
```powershell
Invoke-Expression (& {
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
(zoxide init --hook $hook powershell) -join "`n"
})
```
2020-03-07 21:04:47 +00:00
## Configuration
2020-03-15 18:36:06 +00:00
### `init` flags
2020-05-03 12:41:35 +00:00
- `--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)
2020-03-15 18:36:06 +00:00
- `prompt`: add an entry at every prompt
2020-05-03 12:41:35 +00:00
- `pwd`: add an entry whenever the current directory is changed
- `--no-aliases`: don't define extra aliases like `zi`, `zq`, `za`, and `zr`
2020-03-15 18:36:06 +00:00
2020-03-07 21:04:47 +00:00
### Environment variables
2020-05-03 12:41:35 +00:00
- `$_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
2020-03-07 21:04:47 +00:00
- `$_ZO_MAXAGE`: sets the maximum total rank after which entries start getting deleted
[`dirs` documentation]: https://docs.rs/dirs/latest/dirs/fn.data_local_dir.html