zoxide

  <a href="https://go.warp.dev/zoxide"><img alt="由 Warp 赞助" width="230" src="https://raw.githubusercontent.com/warpdotdev/brand-assets/refs/heads/main/Github/Sponsor/Warp-Github-LG-03.png" /></a>
  <div><sup><b>Warp，专为使用多个 AI Agent 进行编码而打造。</b></sup></div>
  <div><sup>支持 macOS、Linux 和 Windows。</sup></div>
  <div><sup>
    访问
    <a href="https://go.warp.dev/zoxide"><u>warp.dev</u></a>
    了解更多。
  </sup></div>
</td>
<td align="center">
  
  <a href="https://www.recall.ai/careers?ashby_jid=7b02811e-bc91-4ef2-925d-f56a5acac13b&utm_source=github&utm_medium=sponsorship&utm_campaign=zoxide"><img alt="由 Recall.ai 赞助" width="230" src="https://github.com/user-attachments/assets/0c5cb177-561c-4637-bef6-cf584939c829" /></a>
  <div><sup>峰值负载时每秒处理超过 3TB 视频，</sup></div>
  
  <div><sup>现<a href="https://www.recall.ai/careers?ashby_jid=7b02811e-bc91-4ef2-925d-f56a5acac13b&utm_source=github&utm_medium=sponsorship&utm_campaign=zoxide">正在旧金山招聘。</a></sup></div>
</td>

快速入门

![教程][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 (bash 4.4+/fish/zsh only)

[此处][algorithm-matching]可了解有关匹配算法的更多信息。

安装

只需 4 个简单步骤即可安装 zoxide：

1. 安装二进制文件

   zoxide 可在大多数主流平台上运行。如果你的平台未列在下方， 请[提交问题][issues]。

   Linux / WSL

   > 推荐通过安装脚本安装 zoxide： > > ```sh > curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh > ``` > > 或者，你也可以使用包管理器： > > | 发行版 | 软件源 | 安装说明 | > | ------------------- | ----------------------- | ----------------------------------------------------------------- | > | **_任意_** | **[crates.io]** | `cargo install zoxide --locked` | > | _任意_ | [conda-forge] | `conda install -c conda-forge zoxide` | > | _任意_ | [guix] | `guix install zoxide` | > | _任意_ | [Linuxbrew] | `brew install zoxide` | > | _任意_ | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | > | Alpine Linux 3.13+ | [Alpine Linux Packages] | `apk add zoxide` | > | Arch Linux | [Arch Linux Extra] | `pacman -S zoxide` | > | ~~Debian~~[^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 OS~~[^1] | | ~~`apt install zoxide`~~ | > | ~~Raspbian~~[^1] | ~~[Raspbian Packages]~~ | ~~`apt install zoxide`~~ | > | Rhino Linux | [Pacstall Packages] | `pacstall -I zoxide-deb` | > | Slackware 15.0+ | [SlackBuilds] | [安装说明][slackbuilds-howto] | > | Solus | [Solus Packages] | `eopkg install zoxide` | > | ~~Ubuntu~~[^1] | ~~[Ubuntu Packages]~~ | ~~`apt install zoxide`~~ | > | Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` |
   macOS

   要安装 zoxide，请使用包管理器：

   软件源	安装说明
   [crates.io]	cargo install zoxide --locked
   [Homebrew]	brew install zoxide
   [conda-forge]	conda install -c conda-forge zoxide
   [MacPorts]	port install zoxide
   [nixpkgs]	nix-env -iA nixpkgs.zoxide

   或者，在终端中运行以下命令：

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

   Windows

   > zoxide 可用于 PowerShell，以及在 Cygwin、Git Bash 和 MSYS2 中运行的 shell。 > > 推荐通过 `winget` 安装 zoxide： > > ```sh > winget install ajeetdsouza.zoxide > ``` > > 或者，也可以使用其他包管理器： > > | 仓库 | 安装说明 | > | --------------- | ------------------------------------- | > | **[crates.io]** | `cargo install zoxide --locked` | > | [Chocolatey] | `choco install zoxide` | > | [conda-forge] | `conda install -c conda-forge zoxide` | > | [Scoop] | `scoop install zoxide` | > > 如果你使用 Cygwin、Git Bash 或 MSYS2，也可以使用安装脚本： > > ```sh > curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh > ```
   BSD

   安装 zoxide，请使用包管理器：

   发行版	仓库	安装说明
   任意	[crates.io]	cargo install zoxide --locked
   DragonFly BSD	[DPorts]	pkg install zoxide
   FreeBSD	[FreshPorts]	pkg install zoxide
   NetBSD	[pkgsrc]	pkgin install zoxide

   或者，在终端中运行此命令：

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

   Android

   安装 zoxide，请使用包管理器：

   仓库	安装说明
   [Termux]	pkg install zoxide

   或者，在终端中运行此命令：

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

2. 在 shell 中设置 zoxide

   要开始使用 zoxide，请将其添加到你的 shell 中。

   Bash

   将以下内容添加到配置文件的末尾（通常是 ~/.bashrc）：

   eval "$(zoxide init bash)"
   

   Elvish

   将以下内容添加到配置文件的末尾（通常是 ~/.elvish/rc.elv）：

   eval (zoxide init elvish | slurp)
   

   注意： zoxide 仅支持 elvish v0.18.0 及以上版本。

   Fish

   将以下内容添加到配置文件的末尾（通常是 ~/.config/fish/config.fish）：

   zoxide init fish | source
   

   Nushell

   将以下内容添加到 env 文件的末尾（在 Nushell 中运行 $nu.env-path 即可找到该文件）：

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

   然后，将以下内容添加到配置文件的末尾（在 Nushell 中运行 $nu.config-path 即可找到该文件）：

   source ~/.zoxide.nu
   

   注意： zoxide 仅支持 Nushell v0.106.0 及以上版本。

   PowerShell

   将以下内容添加到配置文件的末尾（在 PowerShell 中运行 echo $profile 即可找到该文件）：

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

   Tcsh

   将以下内容添加到配置文件的末尾（通常是 ~/.tcshrc）：

   zoxide init tcsh > ~/.zoxide.tcsh
   source ~/.zoxide.tcsh
   

   Xonsh

   > 将以下内容添加到配置文件的 **末尾**（通常是 `~/.xonshrc`）： > > ```python > execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') > ```
   Zsh

   将以下内容添加到配置文件的 末尾（通常是 ~/.zshrc）：

   eval "$(zoxide init zsh)"
   

   要使补全功能正常工作，必须在调用 compinit 之后 添加上述命令。你可能需要运行 rm ~/.zcompdump*; compinit 来重建补全缓存。

   任意 POSIX shell

   将以下内容添加到配置文件的 末尾：

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

   注意： [Warp] 提供了自己的补全功能，因此不支持 Space+Tab 补全。

3. 安装 fzf ^（可选）

   [fzf] 是一款命令行模糊查找工具，zoxide 使用它来实现补全／交互式选择。可从[此处][fzf-installation]安装。

   注意： 支持的 fzf 最低版本为 v0.51.0。

4. 导入数据 ^（可选）

   如果你目前正在使用以下任一插件，可以考虑将数据导入 zoxide。数据文件会根据各插件的标准约定自动检测。

   zoxide import <plugin>
   

   插件	命令
   atuin	zoxide import atuin
   autojump	zoxide import autojump
   fasd	zoxide import fasd
   z	zoxide import z
   z.lua	zoxide import z.lua
   zsh-z	zoxide import zsh-z

配置

标志

调用 zoxide init 时，可使用以下标志：

• --cmd

  • 更改 z 和 zi 命令的前缀。
  • --cmd j 会将命令改为（j、ji）。
  • --cmd cd 会替换 cd 命令。

• --hook <HOOK>

  • 更改 zoxide 增加目录评分的频率：

    Hook	说明
    none	从不
    prompt	每次 shell 提示符出现时
    pwd (default)	每当目录发生更改时

• --no-cmd

  • 阻止 zoxide 定义 z 和 zi 命令。
  • 如果你想重新定义这些函数，它们仍可在 shell 中通过 __zoxide_z 和 __zoxide_zi 使用。

环境变量

可使用环境变量¹进行配置。必须在调用 zoxide init 之前设置。

• _ZO_DATA_DIR

  • 指定数据库的存储目录。

  • 默认值因操作系统而异：

    操作系统	路径	示例
    Linux / BSD	$XDG_DATA_HOME/zoxide 或 $HOME/.local/share/zoxide	/home/alice/.local/share/zoxide
    macOS	$HOME/Library/Application Support/zoxide	/Users/Alice/Library/Application Support/zoxide
    Windows	%LOCALAPPDATA%\zoxide	C:\Users\Alice\AppData\Local\zoxide

• _ZO_ECHO

  • 设置为 1 时，z 会在导航到匹配的目录之前打印该目录。

• _ZO_EXCLUDE_DIRS

  • 将指定目录排除在数据库之外。

  • 此变量以列表形式提供，使用操作系统特定的字符分隔 [glob][glob]：

    操作系统	分隔符	示例
    Linux / macOS / BSD	:	$HOME:$HOME/private/*
    Windows	;	$HOME;$HOME/private/*

  • 默认设置为 "$HOME"。

• _ZO_FZF_OPTS

  • 交互式选择时传递给 [fzf] 的自定义选项。选项列表请参阅 [man fzf][fzf-man]。

• _ZO_MAXAGE

  • 配置[老化算法][algorithm-aging]，用于限制数据库中的最大条目数。
  • 默认设置为 10000。

• _ZO_RESOLVE_SYMLINKS

  • 设置为 1 时，z 会在将目录添加到数据库之前解析符号链接。

第三方集成