zoxide-comrak-redme.html

<h1><a href="#zoxide" aria-hidden="true" class="anchor" id="user-content-zoxide"></a>zoxide</h1>
<p><a href="https://crates.io/crates/zoxide"><img src="https://img.shields.io/crates/v/zoxide" alt="crates.io" /></a>
<img src="https://github.com/ajeetdsouza/zoxide/workflows/.github/workflows/release.yml/badge.svg" alt=".github/workflows/release.yml" /></p>
<p>A faster way to navigate your filesystem</p>
<h2><a href="#introduction" aria-hidden="true" class="anchor" id="user-content-introduction"></a>Introduction</h2>
<p><code>zoxide</code> is a blazing fast alternative to <code>cd</code>, inspired by
<a href="https://github.com/rupa/z"><code>z</code></a> and <a href="https://github.com/skywind3000/z.lua"><code>z.lua</code></a>.
It keeps track of the directories you use most frequently, and uses a ranking algorithm
to navigate to the best match.</p>
<p><img src="./demo.gif" alt="demo" /></p>
<h2><a href="#examples" aria-hidden="true" class="anchor" id="user-content-examples"></a>Examples</h2>
<pre><code class="language-sh">z foo       # cd to highest ranked directory matching foo
z foo bar   # cd to highest ranked directory matching foo and bar

z foo/      # can also cd into actual directories

zi foo      # cd with interactive selection using fzf
</code></pre>
<h2><a href="#getting-started" aria-hidden="true" class="anchor" id="user-content-getting-started"></a>Getting started</h2>
<h3><a href="#step-1-install-zoxide" aria-hidden="true" class="anchor" id="user-content-step-1-install-zoxide"></a>Step 1: Install zoxide</h3>
<p>zoxide works across all major platforms. If your distribution isn't included in the list below, you can directly install the binary from GitHub:</p>
<pre><code class="language-sh">curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh | sh
</code></pre>
<p>If you would rather not run a script, you can download the binary from the <a href="https://github.com/ajeetdsouza/zoxide/releases">Releases</a> page and add it anywhere in your <code>$PATH</code>.</p>
<h4><a href="#on-linux" aria-hidden="true" class="anchor" id="user-content-on-linux"></a>On Linux</h4>
<table>
<thead>
<tr>
<th>Distribution</th>
<th>Repository</th>
<th>Instructions</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Any</strong></td>
<td><a href="https://crates.io/crates/zoxide">crates.io</a></td>
<td><code>cargo install zoxide</code></td>
</tr>
<tr>
<td><strong>Any</strong></td>
<td><a href="https://formulae.brew.sh/formula-linux/zoxide">Linuxbrew</a></td>
<td><code>brew install zoxide</code></td>
</tr>
<tr>
<td>Alpine Linux</td>
<td><a href="https://pkgs.alpinelinux.org/packages?name=zoxide">Alpine Linux Packages</a></td>
<td><code>apk add zoxide</code></td>
</tr>
<tr>
<td>Arch Linux</td>
<td><a href="https://aur.archlinux.org/packages/zoxide-bin">AUR</a></td>
<td><code>yay -Sy zoxide-bin</code></td>
</tr>
<tr>
<td>CentOS</td>
<td><a href="https://copr.fedorainfracloud.org/coprs/atim/zoxide/">Copr</a></td>
<td><code>dnf copr enable atim/zoxide</code> <br /> <code>dnf install zoxide</code></td>
</tr>
<tr>
<td>Debian Testing</td>
<td><a href="https://packages.debian.org/testing/admin/zoxide">Debian Packages</a></td>
<td><code>apt install zoxide</code></td>
</tr>
<tr>
<td>Fedora</td>
<td><a href="https://src.fedoraproject.org/rpms/rust-zoxide">Fedora Packages</a></td>
<td><code>dnf install zoxide</code></td>
</tr>
<tr>
<td>NixOS</td>
<td><a href="https://nixos.org/nixos/packages.html?attr=zoxide&channel=nixpkgs-unstable">nixpkgs</a></td>
<td><code>nix-env -iA nixpkgs.zoxide</code></td>
</tr>
<tr>
<td>Parrot OS</td>
<td></td>
<td><code>apt install zoxide</code></td>
</tr>
<tr>
<td>Void Linux</td>
<td><a href="https://github.com/void-linux/void-packages/tree/master/srcpkgs/zoxide">Void Linux Packages</a></td>
<td><code>xbps-install -S zoxide</code></td>
</tr>
</tbody>
</table>
<h4><a href="#on-macos" aria-hidden="true" class="anchor" id="user-content-on-macos"></a>On macOS</h4>
<table>
<thead>
<tr>
<th>Repository</th>
<th>Instructions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://crates.io/crates/zoxide">crates.io</a></td>
<td><code>cargo install zoxide</code></td>
</tr>
<tr>
<td><a href="https://formulae.brew.sh/formula/zoxide">Homebrew</a></td>
<td><code>brew install zoxide</code></td>
</tr>
<tr>
<td><a href="https://ports.macports.org/port/zoxide/summary">MacPorts</a></td>
<td><code>port install zoxide</code></td>
</tr>
</tbody>
</table>
<h4><a href="#on-windows" aria-hidden="true" class="anchor" id="user-content-on-windows"></a>On Windows</h4>
<table>
<thead>
<tr>
<th>Repository</th>
<th>Instructions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://crates.io/crates/zoxide">crates.io</a></td>
<td><code>cargo install zoxide</code></td>
</tr>
<tr>
<td><a href="https://github.com/ScoopInstaller/Main/tree/master/bucket/zoxide.json">Scoop</a></td>
<td><code>scoop install zoxide</code></td>
</tr>
</tbody>
</table>
<h4><a href="#on-bsd" aria-hidden="true" class="anchor" id="user-content-on-bsd"></a>On BSD</h4>
<table>
<thead>
<tr>
<th>Distribution</th>
<th>Repository</th>
<th>Instructions</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Any</strong></td>
<td><a href="https://crates.io/crates/zoxide">crates.io</a></td>
<td><code>cargo install zoxide</code></td>
</tr>
<tr>
<td>DragonFly BSD</td>
<td><a href="https://github.com/DragonFlyBSD/DPorts/tree/master/sysutils/zoxide">DPorts</a></td>
<td><code>pkg install zoxide</code></td>
</tr>
<tr>
<td>FreeBSD</td>
<td><a href="https://www.freshports.org/sysutils/zoxide/">FreshPorts</a></td>
<td><code>pkg install zoxide</code></td>
</tr>
<tr>
<td>NetBSD</td>
<td><a href="https://pkgsrc.se/sysutils/zoxide">pkgsrc</a></td>
<td><code>pkgin install zoxide</code></td>
</tr>
</tbody>
</table>
<h4><a href="#on-android" aria-hidden="true" class="anchor" id="user-content-on-android"></a>On Android</h4>
<table>
<thead>
<tr>
<th>Repository</th>
<th>Instructions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/termux/termux-packages/tree/master/packages/zoxide">Termux</a></td>
<td><code>pkg install zoxide</code></td>
</tr>
</tbody>
</table>
<h3><a href="#step-2-install-fzf-optional" aria-hidden="true" class="anchor" id="user-content-step-2-install-fzf-optional"></a>Step 2: Install fzf (optional)</h3>
<p><a href="https://github.com/junegunn/fzf">fzf</a> is a command-line fuzzy finder, used by
zoxide for interactive selection. Installation instructions can be found
<a href="https://github.com/junegunn/fzf#installation">here</a>.</p>
<h3><a href="#step-3-add-zoxide-to-your-shell" aria-hidden="true" class="anchor" id="user-content-step-3-add-zoxide-to-your-shell"></a>Step 3: Add zoxide to your shell</h3>
<p>If you currently use <code>z</code>, <code>z.lua</code>, or <code>zsh-z</code>, you may want to first import
your existing entries into <code>zoxide</code>:</p>
<pre><code class="language-sh">zoxide import --from z /path/to/db
</code></pre>
<p>Alternatively, for <code>autojump</code>:</p>
<pre><code class="language-sh">zoxide import --from autojump /path/to/db
</code></pre>
<h4><a href="#bash" aria-hidden="true" class="anchor" id="user-content-bash"></a>bash</h4>
<p>Add the following line to your configuration file (usually <code>~/.bashrc</code>):</p>
<pre><code class="language-sh">eval &quot;$(zoxide init bash)&quot;
</code></pre>
<h4><a href="#elvish" aria-hidden="true" class="anchor" id="user-content-elvish"></a>elvish</h4>
<p>Add the following line to your configuration file (usually <code>~/.elvish/rc.elv</code>):</p>
<pre><code class="language-sh">eval $(zoxide init elvish | slurp)
</code></pre>
<h4><a href="#fish" aria-hidden="true" class="anchor" id="user-content-fish"></a>fish</h4>
<p>Add the following line to your configuration file (usually <code>~/.config/fish/config.fish</code>):</p>
<pre><code class="language-fish">zoxide init fish | source
</code></pre>
<h4><a href="#nushell" aria-hidden="true" class="anchor" id="user-content-nushell"></a>nushell</h4>
<p>Initialize zoxide's Nushell script:</p>
<pre><code class="language-sh">zoxide init nushell --hook prompt | save ~/.zoxide.nu
</code></pre>
<p>Then, in your Nushell configuration file:</p>
<ul>
<li>Prepend <code>__zoxide_hook;</code> to the <code>prompt</code> variable.</li>
<li>Add the following lines to the <code>startup</code> variable:
<ul>
<li><code>zoxide init nushell --hook prompt | save ~/.zoxide.nu</code></li>
<li><code>source ~/.zoxide.nu</code></li>
</ul>
</li>
</ul>
<h4><a href="#powershell" aria-hidden="true" class="anchor" id="user-content-powershell"></a>powershell</h4>
<p>Add the following line to your profile:</p>
<pre><code class="language-powershell">Invoke-Expression (&amp; {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell) -join &quot;`n&quot;
})
</code></pre>
<h4><a href="#xonsh" aria-hidden="true" class="anchor" id="user-content-xonsh"></a>xonsh</h4>
<p>Add the following line to your configuration file (usually <code>~/.xonshrc</code>):</p>
<pre><code class="language-python">execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
</code></pre>
<h4><a href="#zsh" aria-hidden="true" class="anchor" id="user-content-zsh"></a>zsh</h4>
<p>Add the following line to your configuration file (usually <code>~/.zshrc</code>):</p>
<pre><code class="language-sh">eval &quot;$(zoxide init zsh)&quot;
</code></pre>
<h4><a href="#any-posix-shell" aria-hidden="true" class="anchor" id="user-content-any-posix-shell"></a>Any POSIX shell</h4>
<p>Add the following line to your configuration file:</p>
<pre><code class="language-sh">eval &quot;$(zoxide init posix --hook prompt)&quot;
</code></pre>
<h2><a href="#configuration" aria-hidden="true" class="anchor" id="user-content-configuration"></a>Configuration</h2>
<h3><a href="#init-flags" aria-hidden="true" class="anchor" id="user-content-init-flags"></a><code>init</code> flags</h3>
<ul>
<li><code>--cmd</code>: changes the prefix of predefined aliases (<code>z</code>, <code>zi</code>).
<ul>
<li>e.g. <code>--cmd j</code> would change the aliases to <code>j</code> and <code>ji</code> respectively.</li>
</ul>
</li>
<li><code>--hook &lt;HOOK&gt;</code>: change how often zoxide increments a directory's score:
<ul>
<li><code>none</code>: never automatically add directories to zoxide.</li>
<li><code>prompt</code>: add the current directory to zoxide at every shell prompt.</li>
<li><code>pwd</code>: whenever the user changes directories, add the new directory to zoxide.</li>
</ul>
</li>
<li><code>--no-aliases</code>: don't define extra aliases (<code>z</code>, <code>zi</code>).
<ul>
<li>These functions will still be available in your shell as <code>__zoxide_z</code> and <code>__zoxide_zi</code>, should you choose to use them elsewhere.</li>
</ul>
</li>
</ul>
<h3><a href="#environment-variables" aria-hidden="true" class="anchor" id="user-content-environment-variables"></a>Environment variables</h3>
<p>Be sure to set these before calling <code>zoxide init</code>.</p>
<ul>
<li><code>_ZO_DATA_DIR</code>
<ul>
<li>Specifies the directory in which zoxide should store its database.</li>
<li>The default value varies across OSes:
| OS          | Path                                     | Example                                    |
| ----------- | ---------------------------------------- | ------------------------------------------ |
| Linux / BSD | <code>$XDG_DATA_HOME</code> or <code>$HOME/.local/share</code> | <code>/home/alice/.local/share</code>                 |
| macOS       | <code>$HOME/Library/Application Support</code>      | <code>/Users/Alice/Library/Application Support</code> |
| Windows     | <code>{FOLDERID_RoamingAppData}</code>              | <code>C:\Users\Alice\AppData\Roaming</code>           |</li>
</ul>
</li>
<li><code>_ZO_ECHO</code>
<ul>
<li>When set to <code>1</code>, <code>z</code> will print the matched directory before navigating to it.</li>
</ul>
</li>
<li><code>_ZO_EXCLUDE_DIRS</code>
<ul>
<li>Excludes the specified directories from the database.</li>
<li>This is provided as a list of <a href="https://man7.org/linux/man-pages/man7/glob.7.html">Unix globs</a>, separated by OS-specific characters:
| OS                  | Separator | Example                 |
| ------------------- | --------- | ----------------------- |
| Linux / macOS / BSD | <code>:</code>       | <code>$HOME:$HOME/private/*</code> |
| Windows             | <code>;</code>       | <code>$HOME;$HOME/private/*</code> |</li>
</ul>
</li>
<li><code>_ZO_FZF_OPTS</code>
<ul>
<li>Custom options to pass to <a href="https://github.com/junegunn/fzf">fzf</a>. See <code>man fzf</code> for the list of options.</li>
</ul>
</li>
<li><code>_ZO_MAXAGE</code>
<ul>
<li>Configures the <a href="https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#aging">aging algorithm</a>, which limits the maximum number of entries in the database.</li>
<li>By default, this is set to <code>10000</code>.</li>
</ul>
</li>
<li><code>_ZO_RESOLVE_SYMLINKS</code>
<ul>
<li>When set to <code>1</code>, <code>z</code> will resolve symlinks before adding directories to the database.</li>
</ul>
</li>
</ul>
<h2><a href="#third-party-integrations" aria-hidden="true" class="anchor" id="user-content-third-party-integrations"></a>Third-party integrations</h2>
<ul>
<li><a href="https://github.com/xxh/xxh">xxh</a>, via <a href="https://github.com/xxh/xxh-plugin-prerun-zoxide">xxh-plugin-prerun-zoxide</a></li>
<li><a href="https://github.com/jarun/nnn">nnn</a>, via <a href="https://github.com/jarun/nnn/blob/master/plugins/autojump">autojump plugin</a></li>
</ul>