zoxide/README.md
2022-12-08 23:24:43 +05:30

18 KiB

zoxide

crates.io Downloads Built with Nix

zoxide is a smarter cd command, inspired by z and autojump.

It remembers which directories you use most frequently, so you can "jump" to them in just a few keystrokes.
zoxide works on all major shells.

Getting startedInstallationConfigurationIntegrations

Getting started

Tutorial

z foo              # cd into highest ranked directory matching foo
z foo bar          # cd into highest ranked directory matching foo and bar
z foo /            # cd into a subdirectory starting with foo

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

zi foo             # cd with interactive selection (using fzf)

z foo<SPACE><TAB>  # show interactive completions (zoxide v0.8.0+, bash 4.4+/fish/zsh only)

Read more about the matching algorithm here.

Installation

Step 1: Install zoxide

zoxide runs on most major platforms. If your platform isn't listed below, please open an issue.

Linux

To install zoxide, run this command in your terminal:

curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

Or, you can use a package manager:

Distribution Repository Instructions
Any crates.io cargo install zoxide --locked
Any conda-forge conda install -c conda-forge zoxide
Any Linuxbrew brew install zoxide
Alpine Linux 3.13+ Alpine Linux Packages apk add zoxide
Arch Linux Arch Linux Community pacman -S zoxide
CentOS 7+ Copr dnf copr enable atim/zoxide
dnf install zoxide
Debian 11+ Debian Packages apt install zoxide
Devuan 4.0+ Devuan Packages apt install zoxide
Fedora 32+ Fedora Packages dnf install zoxide
Gentoo GURU Overlay eselect repository enable guru
emerge --sync guru
emerge app-shells/zoxide
Manjaro pacman -S zoxide
NixOS 21.05+ nixpkgs nix-env -iA nixpkgs.zoxide
openSUSE Tumbleweed openSUSE Factory zypper install zoxide
Parrot OS apt install zoxide
Raspbian 11+ Raspbian Packages apt install zoxide
Slackware 15.0+ [SlackBuilds] Instructions
Ubuntu 21.04+ Ubuntu Packages apt install zoxide
Void Linux Void Linux Packages xbps-install -S zoxide
macOS

To install zoxide, use a package manager:

Repository Instructions
crates.io cargo install zoxide --locked
conda-forge conda install -c conda-forge zoxide
Homebrew brew install zoxide
MacPorts port install zoxide

Or, run this command in your terminal:

curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
Windows

To install zoxide, run this command in your command prompt:

curl.exe -A "MS" https://webinstall.dev/zoxide | powershell

Or, you can use a package manager:

Repository Instructions
crates.io cargo install zoxide --locked
Chocolatey choco install zoxide
conda-forge conda install -c conda-forge zoxide
Scoop scoop install zoxide
BSD

To install zoxide, use a package manager:

Distribution Repository Instructions
Any crates.io cargo install zoxide --locked
DragonFly BSD DPorts pkg install zoxide
FreeBSD FreshPorts pkg install zoxide
NetBSD pkgsrc pkgin install zoxide
Android

To install zoxide, use a package manager:

Repository Instructions
Termux pkg install zoxide

Step 2: Add zoxide to your shell

To start using zoxide, add it to your shell.

Bash

Add this to your configuration (usually ~/.bashrc):

eval "$(zoxide init bash)"
Elvish

Add this to your configuration (usually ~/.elvish/rc.elv):

eval (zoxide init elvish | slurp)

Note

zoxide only supports elvish v0.18.0 and above.

Fish

Add this to your configuration (usually ~/.config/fish/config.fish):

zoxide init fish | source

Note

zoxide only supports fish v3.4.0 and above.

Nushell

Add this to your env file (find it by running $nu.env-path in Nushell):

zoxide init nushell | save -f ~/.zoxide.nu

Now, add this to the end of your config file (find it by running $nu.config-path in Nushell):

source ~/.zoxide.nu

Note

zoxide only supports Nushell v0.73.0 and above.

PowerShell

Add this to your configuration (find it by running echo $profile in PowerShell):

# For zoxide v0.8.0+
Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell | Out-String)
})

# For older versions of zoxide
Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell) -join "`n"
})
Xonsh

Add this to your configuration (usually ~/.xonshrc):

execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
Zsh

Add this to your configuration (usually ~/.zshrc):

eval "$(zoxide init zsh)"

For completions to work, the above line must be added after compinit is called. You may have to rebuild your cache by running rm ~/.zcompdump*; compinit.

Any POSIX shell

Add this to your configuration:

eval "$(zoxide init posix --hook prompt)"

Step 3: Install fzf (optional)

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. It can be installed from here.

Note

zoxide only supports fzf v0.21.0 and above.

Step 4: Import your data (optional)

If you currently use any of the following utilities, you may want to import your data into zoxide:

autojump
zoxide import --from autojump path/to/db

The default path varies according to your system:

OS Path Example
Linux $XDG_DATA_HOME/autojump/autojump.txt or $HOME/.local/share/autojump/autojump.txt /home/alice/.local/share/autojump/autojump.txt
macOS $HOME/Library/autojump/autojump.txt /Users/Alice/Library/autojump/autojump.txt
Windows %APPDATA%\autojump\autojump.txt C:\Users\Alice\AppData\Roaming\autojump\autojump.txt
z, z.lua, or zsh-z
zoxide import --from z path/to/db
ZLocation
$db = New-TemporaryFile
(Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db
zoxide import --from z $db

Configuration

Flags

When calling zoxide init, the following flags are available:

  • --cmd
    • Changes the prefix of the z and zi commands.
    • --cmd j would change the commands to (j, ji).
    • --cmd cd would replace the cd command (doesn't work on Nushell / POSIX shells).
  • --hook <HOOK>
    • Changes how often zoxide increments a directory's score:
      Hook Description
      none Never
      prompt At every shell prompt
      pwd Whenever the directory is changed
  • --no-cmd
    • Prevents zoxide from defining the z and zi commands.
    • These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to redefine them.

Environment variables

Environment variables? can be used for configuration. They must be set before zoxide init is called.

  • _ZO_DATA_DIR
    • Specifies the directory in which the database is stored.
    • 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 %LOCALAPPDATA% C:\Users\Alice\AppData\Local
  • _ZO_ECHO
    • When set to 1, z will print the matched directory before navigating to it.
  • _ZO_EXCLUDE_DIRS
    • Excludes the specified directories from the database.
    • This is provided as a list of globs, separated by OS-specific characters:
      OS Separator Example
      Linux / macOS / BSD : $HOME:$HOME/private/*
      Windows ; $HOME;$HOME/private/*
    • By default, this is set to "$HOME".
  • _ZO_FZF_OPTS
    • Custom options to pass to fzf during interactive selection. See man fzf for the list of options.
  • _ZO_MAXAGE
    • Configures the aging algorithm, which limits the maximum number of entries in the database.
    • By default, this is set to 10000.
  • _ZO_RESOLVE_SYMLINKS
    • When set to 1, z will resolve symlinks before adding directories to the database.

Third-party integrations

Application Description Plugin
clink Improved cmd.exe for Windows clink-zoxide
emacs Text editor zoxide.el
felix File manager Natively supported
joshuto File manager Natively supported
lf File manager See the wiki
nnn File manager nnn-autojump
ranger File manager ranger-zoxide
telescope.nvim Fuzzy finder for Neovim telescope-zoxide
vim / neovim Text editor zoxide.vim
xplr File manager zoxide.xplr
xxh Transports shell configuration over SSH xxh-plugin-prerun-zoxide
zabb Finds the shortest possible query for a path Natively supported
zsh-autocomplete Realtime completions for zsh Natively supported