Zoxide

frecencyアルゴリズムを使用して習慣を学習し、シェル間での高速なディレクトリナビゲーションを実現するスマートなcdコマンド。

インストール

パッケージマネージャー

コマンド	説明
`brew install zoxide`	macOSにHomebrewでインストール
`cargo install zoxide --locked`	crates.ioからインストール
`apt install zoxide`	Debian/Ubuntuにインストール
`pacman -S zoxide`	Arch Linuxにインストール
`dnf install zoxide`	Fedoraにインストール
`scoop install zoxide`	WindowsにScoopでインストール
`winget install ajeetdsouza.zoxide`	Windowsにwingetでインストール
`nix-env -i zoxide`	NixOSにインストール
`conda install -c conda-forge zoxide`	Condaでインストール
`curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh`	シェルスクリプトでインストール

シェルの初期化

コマンド	説明
`eval "$(zoxide init bash)"`	Bash用に初期化（.bashrcに追加）
`eval "$(zoxide init zsh)"`	Zsh用に初期化（.zshrcに追加）
`zoxide init fish \| source`	Fish用に初期化（config.fishに追加）
`Invoke-Expression (& { (zoxide init powershell) })`	PowerShell用に初期化
`zoxide init nushell \| save -f ~/.zoxide.nu`	Nushell用に初期化
`eval "$(zoxide init elvish)"`	Elvish用に初期化
`eval (zoxide init xonsh)`	Xonsh用に初期化

シェル設定の例

# Bash — ~/.bashrcに追加
eval "$(zoxide init bash)"

# Zsh — ~/.zshrcに追加
eval "$(zoxide init zsh)"

# Fish — ~/.config/fish/config.fishに追加
zoxide init fish | source

# PowerShell — $PROFILEに追加
Invoke-Expression (& { (zoxide init powershell | Out-String) })

# Nushell — env.nuに追加
zoxide init nushell | save -f ~/.zoxide.nu
source ~/.zoxide.nu

基本的な使い方

コマンド	説明
`z foo`	「foo」にマッチする最高ランクのディレクトリにジャンプ
`z foo bar`	「foo」と「bar」の両方にマッチするディレクトリにジャンプ
`z ~/projects`	正確なパスにジャンプ（cdと同様）
`z ..`	親ディレクトリに移動
`z -`	前のディレクトリに移動
`z`	ホームディレクトリに移動（引数なし）
`zi`	fzfでインタラクティブ選択
`zi foo`	「foo」でプレフィルタしたインタラクティブ選択
`z foo/`	サブディレクトリにジャンプ（末尾スラッシュ）

使用例

# ディレクトリを訪問すると、zoxideがそれを学習します
cd ~/projects/myapp          # zoxideにこのパスを教える
cd ~/documents/reports       # zoxideにこのパスを教える
cd /var/log/nginx            # zoxideにこのパスを教える

# 後で部分一致でジャンプ
z myapp                      # ~/projects/myappにジャンプ
z reports                    # ~/documents/reportsにジャンプ
z nginx                      # /var/log/nginxにジャンプ

# 複数キーワードで一致を絞り込み
z proj myapp                 # ~/projects/myappに特定してマッチ
z doc rep                    # ~/documents/reportsにマッチ

クエリ構文

マッチングルール

コマンド	説明
`z proj`	「proj」を含む任意のディレクトリにマッチ
`z proj rust`	「proj」と「rust」の両方を含むディレクトリにマッチ
`z /home/user/docs`	絶対パスを直接使用
`z docs/`	「docs」というサブディレクトリを優先してマッチ
キーワードはパスコンポーネントにマッチ	「proj」は`/home/user/projects`にマッチ
最後のキーワードはプレフィックスにマッチ可能	`z pr`は`projects`にマッチ
複数キーワードはANDマッチ	全てがパスに含まれる必要がある
マッチングは大文字小文字を区別しない	`z PROJ`は`projects`にマッチ

Frecencyアルゴリズム

コンセプト	説明
Frecency = 頻度 + 最新性	訪問頻度と最近の訪問に基づくスコア
最近の訪問はスコアが高い	今日訪問したディレクトリは先週のものよりスコアが高い
頻繁に訪問するディレクトリはランクが上がる	定期的な使用で時間とともにスコアが上昇
スコアは時間とともに減衰する	未使用のディレクトリは徐々にランクが下がる
データベースは低スコアを自動整理	古い未使用のエントリは自動的に削除される
最大エントリ数は`_ZO_MAXAGE`で制御	デフォルト：10,000エントリ

インタラクティブ選択

コマンド	説明
`zi`	追跡された全ディレクトリでfzfを開く
`zi query`	クエリでプレフィルタしたfzfを開く
fzf内で`↑ / ↓`	結果をナビゲート
fzf内で`Enter`	選択してディレクトリにジャンプ
fzf内で`Escape`	選択をキャンセル
fzf内で入力してフィルタ	結果をさらに絞り込み
`fzf`のインストールが必要	インタラクティブモード用にfzfをインストール
fzf内で`Tab`	選択を切り替え（複数選択モード）

インタラクティブの例

# 追跡された全ディレクトリでインタラクティブファジーファインダーを開く
zi

# 「project」を含むディレクトリにプレフィルタ
zi project

# fzfの出力形式はスコアを表示:
#   3.50   /home/user/projects/myapp
#   2.10   /home/user/projects/api
#   1.20   /var/www/project-site

シェル統合

cdの置き換え

コマンド	説明
`eval "$(zoxide init bash --cmd cd)"`	Bashでcdをzoxideに置き換え
`eval "$(zoxide init zsh --cmd cd)"`	Zshでcdをzoxideに置き換え
`--cmd cd`は`cd`コマンドを置き換え	cdがzoxideを使用するようになる（cd、cdi）
`--cmd j`は`j`と`ji`を作成	カスタムコマンド名を使用
デフォルトは`z`と`zi`を作成	標準のzoxideコマンド

フック設定

コマンド	説明
`--hook pwd`	ディレクトリ変更時にデータベースを更新（デフォルト）
`--hook prompt`	プロンプトごとにデータベースを更新
`--hook none`	自動追跡を無効化

他のツールとの統合

# BashでcdをZoxideに置き換え
eval "$(zoxide init bash --cmd cd)"
# 'cd'がzoxideを使用、'cdi'でインタラクティブを開く

# カスタムコマンド名を使用
eval "$(zoxide init zsh --cmd j)"
# 'j foo'でジャンプ、'ji'でインタラクティブを開く

# fzfと組み合わせて体験を向上
export _ZO_FZF_OPTS="--height 40% --reverse --border"

データベース管理

データベースのクエリ

コマンド	説明
`zoxide query foo`	ジャンプせずにベストマッチを表示
`zoxide query foo --list`	スコア付きで全マッチを一覧表示
`zoxide query foo --score`	frecencyスコア付きでマッチを表示
`zoxide query --all`	データベース全体を一覧表示
`zoxide query --all --score`	スコア付きでデータベースを一覧表示
`zoxide query --exclude /path`	結果から特定のパスを除外
`zoxide query --list \| head -20`	上位20ディレクトリ

エントリの管理

コマンド	説明
`zoxide add /path/to/dir`	手動でディレクトリをデータベースに追加
`zoxide remove /path/to/dir`	データベースからディレクトリを削除
`zoxide edit`	$EDITORでデータベースを開く（インタラクティブ）
データベースは`$_ZO_DATA_DIR/db.zo`に保存	デフォルトのデータベースの場所

データベースの例

# zoxideがマッチするものを確認
zoxide query project --list --score
# 出力:
#    12.00  /home/user/projects/webapp
#     8.50  /home/user/projects/api
#     3.20  /home/user/old-project

# 新しいマシン用にデータベースを手動でシード
zoxide add ~/projects/webapp
zoxide add ~/projects/api
zoxide add ~/.config/nvim

# 古いエントリを削除（削除されたディレクトリ）
zoxide query --all | while read -r dir; do
  [ -d "$dir" ] || zoxide remove "$dir"
done

# バックアップ用にデータベースをエクスポート
zoxide query --all --score > zoxide-backup.txt

他のツールからのインポート

コマンド	説明
`zoxide import --from z path/to/.z`	z.shデータベースからインポート
`zoxide import --from autojump path/to/autojump.txt`	autojumpデータベースからインポート
`zoxide import --merge --from z path/to/.z`	マージインポート（既存エントリを保持）
`zoxide import --from z --merge ~/.z`	一般的なz.shインポート

移行例

# z.shからの移行（最も一般的）
zoxide import --from z ~/.z

# autojumpからの移行
zoxide import --from autojump ~/.local/share/autojump/autojump.txt

# 既存データベースとマージ（上書きしない）
zoxide import --merge --from z ~/.z

# インポート後に確認
zoxide query --all --score | head -20

環境変数

コマンド	説明
`export _ZO_DATA_DIR="$HOME/.local/share/zoxide"`	データベースディレクトリを設定
`export _ZO_ECHO=1`	ジャンプ前にマッチしたディレクトリを表示
`export _ZO_EXCLUDE_DIRS="/tmp/:/private/"`	追跡からディレクトリを除外
`export _ZO_FZF_OPTS="--height 40%"`	zi用のカスタムfzfオプション
`export _ZO_MAXAGE=10000`	データベースの最大エントリ数を設定
`export _ZO_RESOLVE_SYMLINKS=1`	保存前にシンボリックリンクを解決

設定例

# ~/.bashrc または ~/.zshrc — zoxideの完全な設定

# カスタムデータディレクトリを設定
export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

# ジャンプ前にマッチしたディレクトリを表示
export _ZO_ECHO=1

# 一時ディレクトリとシステムディレクトリを除外
export _ZO_EXCLUDE_DIRS="$HOME:$HOME/Downloads:/tmp/*:/private/*"

# インタラクティブモードのfzf表示をカスタマイズ
export _ZO_FZF_OPTS="
  --height 40%
  --layout reverse
  --border rounded
  --preview 'ls -la {2..}'
  --preview-window right:40%
"

# 整理前の最大エントリ数（デフォルト: 10000）
export _ZO_MAXAGE=10000

# シンボリックリンクを正規パスに解決
export _ZO_RESOLVE_SYMLINKS=1

# zoxideを初期化（エクスポートの後に置く必要がある）
eval "$(zoxide init zsh)"

補完 & タブサポート

コマンド	説明
`z <Tab>`	追跡されたディレクトリから自動補完
`z foo<Tab>`	マッチするディレクトリを補完
`zoxide init`経由のBash補完	シェル初期化で自動設定
`zoxide init`経由のZsh補完	シェル初期化で自動設定
`zoxide init`経由のFish補完	シェル初期化で自動設定

ベストプラクティス

zoxideに自然に学習させる — 通常通りシェルを使用すれば、zoxideが習慣からデータベースを構築します。全てのディレクトリを手動でシードする必要はありません。
精度のために2つのキーワードを使用する — 複数のディレクトリがマッチする場合、2つ目のキーワードを追加しましょう：z proj apiはz api単体よりも正確です。
サブディレクトリには末尾スラッシュを使用する — z foo/はカレントディレクトリの「foo」という名前のサブディレクトリを優先し、z fooはデータベース全体を検索します。
最大限の学習のためにcdを置き換える — シェルの初期化で--cmd cdを使用して、zを使うことを覚えている時だけでなく、全てのディレクトリ変更がzoxideにフィードされるようにしましょう。
除外設定を早めに行う — _ZO_EXCLUDE_DIRSを設定して、一時ディレクトリ、ビルドフォルダ、結果を汚すnode_modulesパスをスキップしましょう。
曖昧なジャンプにはziを使用する — どのディレクトリがマッチするか不確かな場合、zi（インタラクティブ）を使って候補をプレビューし選択しましょう。
既存データを移行する — z.sh、autojump、fasdから切り替える場合、zoxide importでデータベースをインポートして、ウォームキャッシュから開始しましょう。
古いエントリを整理する — zoxide editやクリーンアップスクリプトを使って、削除されたディレクトリのエントリを定期的に削除し、結果の関連性を保ちましょう。
データベースをバックアップする — OSの再インストールやマシンの移行前にzoxide query --all --scoreでエクスポートしましょう。
fzfの外観をカスタマイズする — _ZO_FZF_OPTSに--preview 'ls {2..}'を設定して、インタラクティブピッカーでディレクトリの内容を表示しましょう。