zoxide/README.md

275 lines
11 KiB
Markdown
Raw Normal View History

2021-04-11 20:26:48 +00:00
# `zoxide`
2020-03-07 21:04:47 +00:00
2021-05-05 23:01:57 +00:00
> A smarter cd command for your terminal
2020-03-07 21:04:47 +00:00
2021-05-01 21:56:12 +00:00
[![crates.io][crates.io-badge]][crates.io]
2021-05-26 21:04:01 +00:00
[![releases][releases-badge]][Releases]
2021-05-01 21:56:12 +00:00
2021-04-11 20:26:48 +00:00
`zoxide` is a blazing fast replacement for your `cd` command, inspired by
2021-05-26 21:04:01 +00:00
`z` and `z.lua`. It keeps track of the directories you use most
2021-04-11 20:26:48 +00:00
frequently, and uses a ranking algorithm to navigate to the best match.
2020-03-07 21:04:47 +00:00
2021-05-15 04:13:55 +00:00
![Tutorial][tutorial]
2020-05-29 23:38:30 +00:00
2020-03-07 21:04:47 +00:00
## Examples
```sh
2021-04-12 20:27:36 +00:00
z foo # cd into highest ranked directory matching foo
z foo bar # cd into highest ranked directory matching foo and bar
2020-03-07 21:04:47 +00:00
2021-04-12 20:27:36 +00:00
z ~/foo # z also works like a regular cd command
z foo/ # cd into relative path
z .. # cd one level up
z - # cd into previous directory
2020-03-07 21:04:47 +00:00
2021-04-12 20:27:36 +00:00
zi foo # cd with interactive selection (using fzf)
2020-03-07 21:04:47 +00:00
```
2021-04-11 20:26:48 +00:00
Read more about the matching algorithm [here][algorithm-matching].
2020-03-07 21:04:47 +00:00
## Getting started
2021-04-11 20:26:48 +00:00
### Step 1: Install `zoxide`
2020-03-07 21:04:47 +00:00
2021-04-11 20:26:48 +00:00
`zoxide` works across all major platforms. If your distribution isn't included
2021-05-01 21:56:12 +00:00
in the list below, you can download the binary from the [Releases] page and
copy it to your `$PATH`.
2020-07-26 16:39:24 +00:00
2020-10-31 08:15:29 +00:00
#### On Linux
2020-07-26 16:39:24 +00:00
2021-05-13 14:15:28 +00:00
| Distribution | Repository | Instructions |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ |
| **Any** | [crates.io] | `cargo install zoxide` |
| **Any** | [Linuxbrew] | `brew install zoxide` |
| Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` |
| Arch Linux | [AUR] | `yay -Sy zoxide-bin` |
| CentOS 7+ | [Copr] | `dnf copr enable atim/zoxide` <br /> `dnf install zoxide` |
| Debian Testing | [Debian Packages] | `apt install zoxide` |
| Devuan 4.0+ | [Devuan Packages] | `apt install zoxide` |
| Fedora 32+ | [Fedora Packages] | `dnf install zoxide` |
| Gentoo | [dm9pZCAq Overlay] | `eselect repository enable dm9pZCAq` <br /> `emerge --sync dm9pZCAq` <br /> `emerge app-shells/zoxide` |
| NixOS | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` |
| Parrot OS | | `apt install zoxide` |
| Ubuntu 21.04+ | [Ubuntu Packages] | `apt install zoxide` |
| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` |
2020-10-31 08:15:29 +00:00
#### On macOS
2020-03-07 21:04:47 +00:00
2020-10-31 08:15:29 +00:00
| Repository | Instructions |
| ----------- | ---------------------- |
| [crates.io] | `cargo install zoxide` |
| [Homebrew] | `brew install zoxide` |
| [MacPorts] | `port install zoxide` |
2020-03-07 21:04:47 +00:00
2020-10-31 08:15:29 +00:00
#### On Windows
2020-05-24 21:25:00 +00:00
2020-10-31 08:15:29 +00:00
| Repository | Instructions |
| ----------- | ---------------------- |
| [crates.io] | `cargo install zoxide` |
| [Scoop] | `scoop install zoxide` |
2020-03-07 21:04:47 +00:00
2020-10-31 08:15:29 +00:00
#### On BSD
2020-03-07 21:04:47 +00:00
2020-10-31 08:15:29 +00:00
| Distribution | Repository | Instructions |
| ------------- | ------------ | ---------------------- |
| **Any** | [crates.io] | `cargo install zoxide` |
| DragonFly BSD | [DPorts] | `pkg install zoxide` |
| FreeBSD | [FreshPorts] | `pkg install zoxide` |
2020-11-27 09:50:06 +00:00
| NetBSD | [pkgsrc] | `pkgin install zoxide` |
2020-05-24 21:25:00 +00:00
2020-11-06 19:54:14 +00:00
#### On Android
2021-03-14 15:19:51 +00:00
| Repository | Instructions |
| ---------- | -------------------- |
| [Termux] | `pkg install zoxide` |
2020-11-06 19:54:14 +00:00
2021-04-11 20:26:48 +00:00
### Step 2: Install `fzf` (optional)
2020-05-24 21:25:00 +00:00
2021-04-11 20:26:48 +00:00
[`fzf`][fzf] is a command-line fuzzy finder, used by zoxide for interactive
selection. Installation instructions can be found [here][fzf-installation].
2020-03-07 21:04:47 +00:00
2021-04-11 20:26:48 +00:00
### Step 3: Add `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
2021-01-29 21:36:18 +00:00
your existing entries into `zoxide`:
2020-03-15 18:36:06 +00:00
```sh
2021-04-11 20:26:48 +00:00
zoxide import --from z path/to/db
2020-03-15 18:36:06 +00:00
```
2021-04-11 20:26:48 +00:00
Alternatively, for `autojump` (note that scores are not imported):
2021-01-29 21:36:18 +00:00
```sh
2021-04-11 20:26:48 +00:00
zoxide import --from autojump path/to/db
2021-01-29 21:36:18 +00:00
```
2021-04-11 20:26:48 +00:00
#### `bash`
2020-03-08 19:12:09 +00:00
2021-04-27 12:07:38 +00:00
Add this to your configuration (usually `~/.bashrc`):
2020-03-08 19:12:09 +00:00
```sh
eval "$(zoxide init bash)"
2020-03-08 19:12:09 +00:00
```
2021-04-11 20:26:48 +00:00
#### `elvish`
2021-04-08 18:35:42 +00:00
2021-04-27 12:07:38 +00:00
Add this to your configuration (usually `~/.elvish/rc.elv`):
2021-04-08 18:35:42 +00:00
```sh
2021-05-26 21:04:01 +00:00
eval (zoxide init elvish | slurp)
2021-04-08 18:35:42 +00:00
```
2021-04-11 20:26:48 +00:00
#### `fish`
2020-03-08 19:05:37 +00:00
2021-04-27 12:07:38 +00:00
Add this to your configuration (usually `~/.config/fish/config.fish`):
2020-03-08 19:05:37 +00:00
2021-03-31 16:45:43 +00:00
```fish
zoxide init fish | source
2020-03-08 16:15:06 +00:00
```
2021-04-11 20:26:48 +00:00
#### `nushell`
2021-03-14 15:19:51 +00:00
2021-03-31 16:45:43 +00:00
Initialize zoxide's Nushell script:
```sh
zoxide init nushell --hook prompt | save ~/.zoxide.nu
```
2021-04-27 12:07:38 +00:00
Add this to your configuration (usually `~/.config/nu/config.toml`):
2021-03-31 16:45:43 +00:00
2021-04-27 12:07:38 +00:00
```toml
prompt = "__zoxide_hook;__zoxide_prompt"
startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]
```
You can replace `__zoxide_prompt` with a custom prompt.
2021-03-31 16:45:43 +00:00
2021-04-11 20:26:48 +00:00
#### `powershell`
2020-05-06 06:03:06 +00:00
2021-04-27 12:07:38 +00:00
Add this to your configuration (the location is stored in `$profile`):
2020-05-06 06:03:06 +00:00
```powershell
Invoke-Expression (& {
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
(zoxide init --hook $hook powershell) -join "`n"
})
```
2021-04-11 20:26:48 +00:00
#### `xonsh`
2020-10-30 18:52:09 +00:00
2021-04-27 12:07:38 +00:00
Add this to your configuration (usually `~/.xonshrc`):
2020-10-30 18:52:09 +00:00
2021-03-31 16:45:43 +00:00
```python
2020-10-30 18:52:09 +00:00
execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
```
2021-04-11 20:26:48 +00:00
#### `zsh`
2020-05-24 21:25:00 +00:00
2021-04-27 12:07:38 +00:00
Add this to your configuration (usually `~/.zshrc`):
2020-05-24 21:25:00 +00:00
```sh
eval "$(zoxide init zsh)"
```
2020-10-31 08:15:29 +00:00
#### Any POSIX shell
2021-04-27 12:07:38 +00:00
Add this to your configuration:
2020-10-31 08:15:29 +00:00
```sh
eval "$(zoxide init posix --hook prompt)"
```
2020-03-07 21:04:47 +00:00
## Configuration
2020-03-15 18:36:06 +00:00
### `init` flags
2021-03-14 15:19:51 +00:00
- `--cmd`: changes the prefix of predefined aliases (`z`, `zi`).
- e.g. `--cmd j` would change the aliases to `j` and `ji` respectively.
- `--hook <HOOK>`: change how often zoxide increments a directory's score:
- `none`: never automatically add directories to zoxide.
- `prompt`: add the current directory to zoxide at every shell prompt.
2021-04-11 20:26:48 +00:00
- `pwd`: whenever the user changes directories, add the new directory to
zoxide.
2021-03-14 15:19:51 +00:00
- `--no-aliases`: don't define extra aliases (`z`, `zi`).
2021-04-11 20:26:48 +00:00
- These functions will still be available in your shell as `__zoxide_z` and
`__zoxide_zi`, should you choose to use them elsewhere.
2020-03-15 18:36:06 +00:00
2020-03-07 21:04:47 +00:00
### Environment variables
2021-03-31 16:45:43 +00:00
Be sure to set these before calling `zoxide init`.
2021-03-14 15:19:51 +00:00
- `_ZO_DATA_DIR`
- Specifies the directory in which zoxide should store its database.
- The default value varies across OSes:
| OS | Path | Example |
| ----------- | ---------------------------------------- | ------------------------------------------ |
| Linux / BSD | `$XDG_DATA_HOME` or `$HOME/.local/share` | `/home/alice/.local/share` |
| macOS | `$HOME/Library/Application Support` | `/Users/Alice/Library/Application Support` |
| Windows | `{FOLDERID_RoamingAppData}` | `C:\Users\Alice\AppData\Roaming` |
- `_ZO_ECHO`
2021-04-11 20:26:48 +00:00
- When set to `1`, `z` will print the matched directory before navigating to
it.
2021-03-14 15:19:51 +00:00
- `_ZO_EXCLUDE_DIRS`
- Excludes the specified directories from the database.
2021-04-11 20:26:48 +00:00
- This is provided as a list of [globs][glob], separated by OS-specific
characters:
2021-03-14 15:19:51 +00:00
| OS | Separator | Example |
| ------------------- | --------- | ----------------------- |
| Linux / macOS / BSD | `:` | `$HOME:$HOME/private/*` |
| Windows | `;` | `$HOME;$HOME/private/*` |
- By default, this is set to `"$HOME"`.
2021-03-14 15:19:51 +00:00
- `_ZO_FZF_OPTS`
2021-04-11 20:26:48 +00:00
- Custom options to pass to [`fzf`][fzf]. See `man fzf` for the list of
options.
2021-03-14 15:19:51 +00:00
- `_ZO_MAXAGE`
2021-04-11 20:26:48 +00:00
- Configures the [aging algorithm][algorithm-aging], which limits the maximum
number of entries in the database.
2021-03-14 15:19:51 +00:00
- By default, this is set to `10000`.
- `_ZO_RESOLVE_SYMLINKS`
2021-04-11 20:26:48 +00:00
- When set to `1`, `z` will resolve symlinks before adding directories to the
database.
2021-03-14 15:19:51 +00:00
## Third-party integrations
2021-04-11 20:26:48 +00:00
- [nnn], via [autojump plugin][nnn-autojump]
2021-05-18 02:28:16 +00:00
- [telescope-zoxide]
2021-04-11 20:26:48 +00:00
- [xxh], via [xxh-plugin-prerun-zoxide]
2021-05-18 02:28:16 +00:00
- [zoxide.vim]
- [zsh-autocomplete]
2021-04-11 20:26:48 +00:00
[algorithm-aging]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#aging
[algorithm-matching]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#matching
2021-03-14 15:19:51 +00:00
[alpine linux packages]: https://pkgs.alpinelinux.org/packages?name=zoxide
[aur]: https://aur.archlinux.org/packages/zoxide-bin
[copr]: https://copr.fedorainfracloud.org/coprs/atim/zoxide/
2021-04-11 20:26:48 +00:00
[crates.io-badge]: https://img.shields.io/crates/v/zoxide
2020-10-31 08:15:29 +00:00
[crates.io]: https://crates.io/crates/zoxide
2021-03-14 15:19:51 +00:00
[debian packages]: https://packages.debian.org/testing/admin/zoxide
2021-04-28 19:53:43 +00:00
[devuan packages]: https://pkginfo.devuan.org/cgi-bin/package-query.html?c=package&q=zoxide
2021-05-13 14:15:28 +00:00
[dm9pzcaq overlay]: https://github.com/gentoo-mirror/dm9pZCAq
2021-03-14 15:19:51 +00:00
[dports]: https://github.com/DragonFlyBSD/DPorts/tree/master/sysutils/zoxide
[fedora packages]: https://src.fedoraproject.org/rpms/rust-zoxide
2021-04-11 20:26:48 +00:00
[freshports]: https://www.freshports.org/sysutils/zoxide/
[fzf-installation]: https://github.com/junegunn/fzf#installation
[fzf]: https://github.com/junegunn/fzf
[glob]: https://man7.org/linux/man-pages/man7/glob.7.html
2021-03-14 15:19:51 +00:00
[homebrew]: https://formulae.brew.sh/formula/zoxide
[linuxbrew]: https://formulae.brew.sh/formula-linux/zoxide
[macports]: https://ports.macports.org/port/zoxide/summary
2021-04-11 20:26:48 +00:00
[nixpkgs]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/zoxide/default.nix
[nnn-autojump]: https://github.com/jarun/nnn/blob/master/plugins/autojump
[nnn]: https://github.com/jarun/nnn
2020-11-27 09:50:06 +00:00
[pkgsrc]: https://pkgsrc.se/sysutils/zoxide
2021-04-11 20:26:48 +00:00
[releases]: https://github.com/ajeetdsouza/zoxide/releases
2021-05-26 21:04:01 +00:00
[releases-badge]: https://img.shields.io/github/v/release/ajeetdsouza/zoxide
2021-03-14 15:19:51 +00:00
[scoop]: https://github.com/ScoopInstaller/Main/tree/master/bucket/zoxide.json
2021-05-18 02:28:16 +00:00
[telescope-zoxide]: https://github.com/jvgrootveld/telescope-zoxide
2021-03-14 15:19:51 +00:00
[termux]: https://github.com/termux/termux-packages/tree/master/packages/zoxide
2021-05-15 04:13:55 +00:00
[tutorial]: contrib/tutorial.webp
2021-04-28 19:53:43 +00:00
[ubuntu packages]: https://packages.ubuntu.com/hirsute/zoxide
2021-03-14 15:19:51 +00:00
[void linux packages]: https://github.com/void-linux/void-packages/tree/master/srcpkgs/zoxide
2021-04-11 20:26:48 +00:00
[xxh-plugin-prerun-zoxide]: https://github.com/xxh/xxh-plugin-prerun-zoxide
[xxh]: https://github.com/xxh/xxh
2021-05-15 20:06:06 +00:00
[zoxide.vim]: https://github.com/nanotee/zoxide.vim
2021-05-18 02:28:16 +00:00
[zsh-autocomplete]: https://github.com/marlonrichert/zsh-autocomplete