ZOXIDE(1)

🌸 ZOXIDE(1) 🌸

ok so bestie, welcome to zoxide — aka the manual page for the smartest little cd you will ever meet. this is zoxide(1), and i'm gonna walk you through literally everything, no skips, no gatekeeping. 💖

---

✨ NAME ✨

zoxide — a smarter cd command

---

✨ SYNOPSIS ✨

zoxide SUBCOMMAND [OPTIONS]

---

✨ DESCRIPTION ✨

okay so picture this: zoxide is a smarter cd command for your terminal. it keeps track of the directories you use most frequently, and then uses a ranking algorithm to navigate you straight to the best match. it's giving personal assistant but for your filesystem. 🧚

---

✨ USAGE ✨

here's the vibe in action:

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)

heads up bestie: that <SPACE><TAB> trick only works on bash 4.4+, fish, and zsh. know your shell, know your power. 💅

---

✨ SUBCOMMANDS ✨

each one has its own whole manual page, so go read those too:

• zoxide-add(1) — add a new directory to the database, or increment its rank. ✨
• zoxide-import(1) — import entries from another application. bring your friends, we're welcoming here. 🫶
• zoxide-init(1) — generate shell configuration. this is the one that sets you up.
• zoxide-query(1) — search for a directory in the database. 🔍
• zoxide-remove(1) — remove a directory from the database. it's not you, it's the frecency score. 💀

---

✨ OPTIONS ✨

• -h, --help — print help information. the classic "wait what do i do" button.
• -V, --version — print version information. for when you gotta know which zoxide you're running, iykyk.

---

✨ ENVIRONMENT VARIABLES ✨

ok so these are how you configure stuff. important: they have to be set before zoxide-init(1) is called, or they just won't take. set them first, bestie. 🌈

• _ZO_DATA_DIR — specifies the directory in which the database is stored. the default value varies across OSes:
  • Linux/BSD — $XDG_DATA_HOME or $HOME/.local/share, eg. /home/alice/.local/share
  • macOS — $HOME/Library/Application Support, eg. /Users/Alice/Library/Application Support
  • Windows — %LOCALAPPDATA%, eg. C:\Users\Alice\AppData\Local
• _ZO_ECHO — when set to 1, z will print the matched directory before navigating to it. little spoiler alert. 👀
• _ZO_EXCLUDE_DIRS — prevents the specified directories from being added to the database. this is provided as a list of globs, separated by OS-specific characters:
  • Linux/macOS/BSD — :, eg. $HOME:$HOME/private/*
  • Windows — ;, eg. $HOME;$HOME/private/*

by default, this is set to $HOME. and after setting this up, you might need to use zoxide-remove(1) to remove any existing entries from the database. spring cleaning era. 🧹

• _ZO_FZF_OPTS — custom options to pass to fzf(1) during interactive selection. see the manpage for the full 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.

---

✨ ALGORITHM ✨

the math is mathing, and honestly? it's iconic. 👑

AGING

zoxide uses a parameter called _ZO_MAXAGE to limit the number of entries in the database based on usage patterns. if the total FRECENCY of the directories in the database exceeds this value, we divide each directory's score by a factor k — such that the new total becomes ~90% of _ZO_MAXAGE. thereafter, if the new score of any directory falls below 1, it is removed from the database.

theoretically, the maximum number of directories in the database is 4 * _ZO_MAXAGE, although it is lower in practice. theory vs. practice, the eternal saga. 💀

FRECENCY

each directory in zoxide is given a score, starting with 1 the first time it is accessed. every subsequent access increases the score by 1. when a query is made, we calculate frecency based on the last time the directory was accessed:

• within the last hour — score * 4 🔥
• within the last day — score * 2 ✨
• within the last week — score / 2 🌸
• otherwise — score / 4 🥀

---

✨ REPORTING BUGS ✨

for any issues, feature requests, or questions, please visit:

https://github.com/ajeetdsouza/zoxide/issues

come through, we don't bite. 🫶

---

✨ AUTHOR ✨

Ajeet D'Souza <98ajeet@gmail.com>

---

and that's the whole page, bestie!! this was zoxide(1), from zoxide, dated 2021-04-12. go forth and z your way around the filesystem, you absolute main character. 💅✨🦋💖