zoxide: умный переход по каталогам

zoxide запоминает каталоги, в которых вы бываете, и позволяет переходить в них по части имени. Вместо длинного cd ~/projects/backend/services/api достаточно z api. Утилита написана на Rust, работает локально, не требует сети и встраивается в bash, zsh, fish и другие оболочки. Разберём установку, режимы поиска, настройку и типичные конфликты.

Идея frecency

zoxide хранит не только путь, но и историю обращений. Рейтинг каталога складывается из частоты и свежести — подход, который называют frecency. Поэтому z doc приведёт в недавний рабочий каталог, а не в одноимённую папку, открытую год назад.

База лежит в ~/.local/share/zoxide/db.zo и доступна только пользователю. Сетевых запросов нет, телеметрии тоже. При этом база содержит пути, которые вы посещали, — это стоит учитывать на общей машине.

zoxide не заменяет файловый менеджер и не индексирует содержимое файлов. Это надстройка над cd, которая экономит нажатия, работает предсказуемо и не мешает привычным командам. Утилита не требует демона и не держит файлы открытыми между вызовами.

Установка

В Debian 12, Ubuntu 24.04 и новее пакет есть в репозитории. Если версия старая или дистрибутив другой, используйте официальный установщик либо cargo.

sudo apt install zoxide
zoxide --version
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
cargo install zoxide --locked

После установки проверьте путь: which zoxide. Установщик кладёт бинарник в ~/.local/bin, поэтому каталог должен быть в PATH. Для обновления достаточно повторить установку.

Подключение к оболочке

Инициализация добавляет функцию и привязки. Строку нужно добавить в конец конфигурации, после всех остальных настроек оболочки, иначе другой плагин может перезаписать функцию.

echo 'eval "$(zoxide init bash)"' >> ~/.bashrc
echo 'eval "$(zoxide init zsh)"' >> ~/.zshrc
echo 'zoxide init fish | source' >> ~/.config/fish/config.fish
exec $SHELL -l

По умолчанию команда называется z, а интерактивный режим — zi. Ключ —cmd cd заставляет zoxide подменить сам cd: тогда любой переход обновляет базу, а z остаётся для быстрых прыжков. Некоторым удобнее короткое имя j.

eval "$(zoxide init bash --cmd cd)"
eval "$(zoxide init zsh --cmd j)"
type z
zoxide init --help | head -20

Повседневные команды

Аргументы ищутся как подстроки и могут относиться к разным частям пути. Команда z proj api найдёт каталог, в пути которого есть и proj, и api. Если совпадений несколько, побеждает лучший рейтинг.

z api
z proj api
z -
zi
zoxide query api

zi открывает интерактивный список через fzf: стрелки, ввод для фильтра, Enter для перехода. Если fzf не установлен, поставьте его отдельно — без него интерактивный режим не работает.

sudo apt install fzf
zi
zoxide query -l | head -20
zoxide query -s api

Ключ -l выводит все известные каталоги, -s показывает оценку и путь. Эти команды удобны для диагностики: если нужной папки нет в списке, значит, вы не заходили в неё после установки.

Настройка через переменные

Поведение задаётся переменными окружения, их ставят до инициализации оболочки. _ZO_ECHO=1 печатает путь после перехода, _ZO_MAXAGE ограничивает размер базы, _ZO_RESOLVE_SYMLINKS заставляет хранить реальные пути.

export _ZO_ECHO=1
export _ZO_MAXAGE=10000
export _ZO_RESOLVE_SYMLINKS=1
export _ZO_FZF_OPTS="--height=40% --layout=reverse"

_ZO_EXCLUDE_DIRS принимает шаблоны через двоеточие. Исключите домашний каталог целиком, временные папки и всё, что содержит секреты, — так база не будет разрастаться и не попадёт лишнее.

export _ZO_EXCLUDE_DIRS="$HOME:$HOME/private/*:/tmp/*:/run/user/*"
zoxide query -l | wc -l
ls -l ~/.local/share/zoxide/db.zo

Если база нужна в другом месте, задайте _ZO_DATA_DIR. Это пригодится, когда домашний каталог на сетевом диске, а базу хочется держать локально.

export _ZO_DATA_DIR="$HOME/.cache/zoxide"
mkdir -p "$_ZO_DATA_DIR"
chmod 700 "$_ZO_DATA_DIR"

Производительность и переносимость

База обновляется при каждом переходе, поэтому z не замедляет оболочку. Файл небольшой: даже десятки тысяч записей занимают единицы мегабайт. Если база повреждена, zoxide не запустится — уберите файл, и он создастся заново, но история пропадёт.

du -h ~/.local/share/zoxide/db.zo
mv ~/.local/share/zoxide/db.zo ~/db.zo.broken
zoxide add ~/projects/api
zoxide query -l | wc -l

Настройки удобно держать в одном файле и подключать из bash и zsh. Не дублируйте export в двух местах: переменные должны быть заданы до вызова zoxide init, иначе оболочка получит старые значения. Для переноса на новую машину скопируйте db.zo или импортируйте его командой zoxide import.

Импорт и очистка

При переходе с autojump или z историю можно перенести. zoxide понимает оба формата и не дублирует записи.

zoxide import --from autojump ~/.local/share/autojump/autojump.txt
zoxide import --from z ~/.z
zoxide import --from zoxide ~/backup/db.zo
zoxide edit

Команда zoxide edit открывает интерактивный редактор базы: можно удалить отдельные записи или почистить всё. Для точечного удаления есть zoxide remove с путём. Перед массовой чисткой сделайте копию файла базы. Автоматической синхронизации у утилиты нет: если база нужна на нескольких машинах, файл переносят вручную.

zoxide remove ~/projects/old
cp ~/.local/share/zoxide/db.zo ~/zoxide-backup.zo
zoxide query -l | wc -l

Конфликты и диагностика

Если z не находится, проверьте порядок строк в конфиге и тип функции: type z должен показать shell function, а не внешнюю команду. В zsh хук ставят после oh-my-zsh, иначе привязки клавиш перезапишутся.

Если переход ведёт не туда, посмотрите рейтинг через zoxide query -s и удалите лишний каталог. Одинаковые имена папок в разных проектах — обычная причина: помогает второй аргумент или zi.

type z
zoxide query -s api
zoxide remove /path/to/wrong/dir
echo $PATH | tr ':' '\n' | grep local

В скриптах zoxide не нужен: там лучше явный cd с проверкой каталога. Подмена cd в неинтерактивной оболочке может сломать ожидания других программ, поэтому инициализацию добавляют только в интерактивный конфиг.

Чек-лист

• zoxide установлен, бинарник доступен в PATH.
• Хук добавлен в конец конфигурации оболочки.
• fzf установлен, zi открывает список.
• Исключены домашний каталог, /tmp и приватные папки.
• База защищена правами 700, копия сделана.
• В скриптах используется обычный cd.

Итог

zoxide — небольшая утилита, которая заметно сокращает переходы по каталогам и почти не требует настройки. Достаточно установить пакет, добавить одну строку в конфиг и привыкнуть к z. Дальше стоит настроить исключения и интерактивный режим, чтобы база оставалась чистой, а поиск — предсказуемым.