Skip to content

Latest commit

 

History

History
560 lines (469 loc) · 24.2 KB

README.md

File metadata and controls

560 lines (469 loc) · 24.2 KB
Raw

Special thanks to:

Warp
Warp is a modern, Rust-based terminal with AI built in so you and your team can build great software, faster.
Visit warp.dev to learn more.

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 started • Installation • Configuration • Integrations

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

zoxide can be installed in 4 easy steps:

  1. Install binary

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

    Linux / WSL

    The recommended way to install zoxide is via the install script:

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

    Or, you can use a package manager:

    Distribution Repository Instructions
    Any crates.io cargo install zoxide --locked
    Any asdf asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git
    asdf install zoxide latest
    Any conda-forge conda install -c conda-forge zoxide
    Any guix guix install zoxide
    Any Linuxbrew brew install zoxide
    Any nixpkgs nix-env -iA nixpkgs.zoxide
    Alpine Linux 3.13+ Alpine Linux Packages apk add zoxide
    Arch Linux Arch Linux Extra pacman -S zoxide
    CentOS 7+ Copr dnf copr enable atim/zoxide
    dnf install zoxide
    Debian 11+1 Debian Packages apt install zoxide
    Devuan 4.0+ Devuan Packages apt install zoxide
    Exherbo Linux Exherbo packages cave resolve -x repository/rust
    cave resolve -x zoxide
    Fedora 32+ Fedora Packages dnf install zoxide
    Gentoo Gentoo Packages emerge app-shells/zoxide
    Manjaro pacman -S zoxide
    openSUSE Tumbleweed openSUSE Factory zypper install zoxide
    Parrot OS1 apt install zoxide
    Raspbian 11+1 Raspbian Packages apt install zoxide
    Rhino Linux Pacstall Packages pacstall -I zoxide-deb
    Slackware 15.0+ SlackBuilds Instructions
    Solus Solus Packages eopkg install zoxide
    Ubuntu 21.04+1 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
    Homebrew brew install zoxide
    asdf asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git
    asdf install zoxide latest
    conda-forge conda install -c conda-forge zoxide
    MacPorts port install zoxide
    nixpkgs nix-env -iA nixpkgs.zoxide

    Or, run this command in your terminal:

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

    zoxide works with PowerShell, as well as shells running in Cygwin, Git Bash, and MSYS2.

    The recommended way to install zoxide is via winget:

    winget install ajeetdsouza.zoxide

    Or, you can use an alternative 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

    If you're using Cygwin, Git Bash, or MSYS2, you can also use the install script:

    curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
    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

    Or, run this command in your terminal:

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

    To install zoxide, use a package manager:

    Repository Instructions
    Termux pkg install zoxide

    Or, run this command in your terminal:

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

  2. Setup zoxide on your shell

    To start using zoxide, add it to your shell.

    Bash

    Add this to the end of your config file (usually ~/.bashrc):

    eval "$(zoxide init bash)"
    Elvish

    Add this to the end of your config file (usually ~/.elvish/rc.elv):

    eval (zoxide init elvish | slurp)

    Note zoxide only supports elvish v0.18.0 and above.

    Fish

    Add this to the end of your config file (usually ~/.config/fish/config.fish):

    zoxide init fish | source
    Ksh

    Add this to the end of your config file (usually ~/.kshrc):

    # ksh93
eval "$(zoxide init ksh)"

# mksh, oksh, etc.
eval "$(zoxide init ksh --hook=prompt)"
    Nushell

    Add this to the end of 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.89.0+.

    PowerShell

    Add this to the end of your config file (find it by running echo $profile in PowerShell):

    Invoke-Expression (& { (zoxide init powershell | Out-String) })
    Xonsh

    Add this to the end of your config file (usually ~/.xonshrc):

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

    Add this to the end of your config file (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 completions cache by running rm ~/.zcompdump*; compinit.

    Any POSIX shell

    Add this to the end of your config file:

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

  3. Install fzf (optional)

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

    Note zoxide only supports fzf v0.33.0 and above.

  4. Import your data (optional)

    If you currently use any of these plugins, you may want to import your data into zoxide:

    autojump

    Run this command in your terminal:

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

    The path usually 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
    fasd, z, z.lua, zsh-z

    Run this command in your terminal:

    zoxide import --from=z "path/to/z/db"

    The path usually varies according to your system:

    Plugin Path
    fasd $_FASD_DATA or $HOME/.fasd
    z (bash/zsh) $_Z_DATA or $HOME/.z
    z (fish) $Z_DATA or $XDG_DATA_HOME/z/data or $HOME/.local/share/z/data
    z.lua (bash/zsh) $_ZL_DATA or $HOME/.zlua
    z.lua (fish) $XDG_DATA_HOME/zlua/zlua.txt or $HOME/.local/share/zlua/zlua.txt or $_ZL_DATA
    zsh-z $ZSHZ_DATA or $_Z_DATA or $HOME/.z
    ZLocation

    Run this command in PowerShell:

    $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.
  • --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 variables2 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
aerc Email client Natively supported
alfred macOS launcher alfred-zoxide
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
t tmux session manager Natively supported
tmux-session-wizard tmux session manager Natively supported
vim / neovim Text editor zoxide.vim
xplr File manager zoxide.xplr
xxh Transports shell configuration over SSH xxh-plugin-prerun-zoxide
yazi File manager Natively supported
zabb Finds the shortest possible query for a path Natively supported
zsh-autocomplete Realtime completions for zsh Natively supported

Footnotes

  1. Debian / Ubuntu derivatives update their packages very slowly. If you're using one of these distributions, consider using the install script instead. ↩ ↩2 ↩3 ↩4

  2. If you're not sure how to set an environment variable on your shell, check out the wiki. ↩