envocabulary

現在のシェル内のすべての変数について、その変数を設定したファイルと行番号、またはその変数を注入したサブシステム（direnv、launchd、terminal、SSH、system）を見つけます。さらに、シェル設定がN個のファイルやバックアップに散らばって把握できなくなったときのための、いくつかの静的ファイルコマンドも提供します。

このツールを作った理由は、数ヶ月ごとに同じ時間を費やして、JAVA_HOME や PATH が予期しない場所を指している理由を追跡していたからです。which はコマンドを知っており、direnv status は direnv を知り、launchctl getenv は launchd を知っていますが、どれも ~/.zshrc:42 が実際の書き手であることは教えてくれません。

macOS、Linux、FreeBSD 上の zsh および bash で動作します。

「ああ」と気づく瞬間

grep -r JAVA_HOME ~ は変数に言及しているすべてのファイルを表示しますが、出力からは現在のシェルでどの代入が有効かは明確ではありません。

$ envocabulary explain --chain JAVA_HOME
JAVA_HOME
  origin   shell-file
  primary  ~/helpers.sh:3
  chain    ~/.zshrc → ~/helpers.sh
  writers
    ~/.zshenv:8
    ~/helpers.sh:3  (winner)
  value    [hidden, use --values]

インストール

ワンライナー（OS/アーキテクチャを検出し、バイナリを $PATH に配置し、macOS では Gatekeeper をクリアします）：

curl -fsSL https://raw.githubusercontent.com/sreckoskocilic/envocabulary/main/install.sh | sh

または go install github.com/sreckoskocilic/envocabulary/cmd/envocabulary@latest。プリビルドバイナリと Linux パッケージ（.deb / .rpm / .apk / .pkg.tar.zst）はリリースページにあります。

コマンド

ライブ環境（実行中のシェルを調査）：

• scan (デフォルト) — 現在の環境内のすべての変数を origin でグループ化して表示します
• explain NAME — 指定された変数の完全な属性情報を表示します
• path [VARNAME...] — コロン区切りのパス変数のエントリごとの属性情報を表示します；--check で存在しないエントリを見つけます

静的ファイル：

• inventory — すべてのシェル設定ファイルを一覧表示し、定義の種類ごとにカウントします
• catalog — すべての設定ファイルをマージして、シェル設定全体を出力します
• dedup — エクスポート、代入、エイリアス、関数のファイル間重複レポート
• dangling — 有効なターゲットを参照しなくなった設定ファイルエントリを一覧表示します
• lost — 孤立またはバックアップの設定ファイルにのみ存在する定義を一覧表示します
• report — 結合監査：削除可能、レビュー（値が変更された重複）、ダングリング、孤立ファイル；--html でタイムスタンプ付きの .html ファイルをカレントディレクトリに書き込みます
• clean [--full] FILE — 削除すべき行を一覧表示します；--full で完全にクリーンアップした内容を出力します

その他：

• -V, --version — バージョン、コミット、ビルド日付を表示

envocabulary <cmd> -h でフラグを確認。

以下のサンプル出力では簡潔さのために ~/ を使用していますが、ツールは report を除き、常に絶対パスを出力します。

別の例：壊れた参照を見つける

dangling は、有効なターゲットを参照しなくなった設定ファイルのエントリをリストアップします — JAVA_HOME=/opt/jdk-i-uninstalled や source ~/dotfiles/work-old.zsh のような残骸です。

$ envocabulary dangling
## ~/.zshrc
  ~/.zshrc:14  source   → ~/dotfiles/work-old.zsh  (source target missing)
  ~/.zshrc:42  export JAVA_HOME  → /opt/jdk-11  (path does not exist)

別の例：PATH エントリの追跡

path は、PATH（または MANPATH、FPATH など）の各エントリがどこで導入されたかを表示します：

$ envocabulary path PATH
## PATH
  /opt/homebrew/bin       ~/.zprofile:21
  /usr/local/bin          ~/.zprofile:1
  /usr/bin                /etc/zprofile:1
  /bin                    /etc/zprofile:1
  /usr/sbin               /etc/zprofile:1
  /sbin                   /etc/zprofile:1
  ~/.cargo/bin            ~/.zshrc:22

シェル起動時の代入に一致しなかったエントリは inherited と表示されます。

--check は、ディレクトリが存在しなくなったエントリに絞り込み、編集すべき設定ファイルまで追跡します：

$ envocabulary path --check PATH
## PATH
  /opt/homebrew/Cellar/go/1.25.1/libexec/bin  ~/.zshrc:17  (does not exist)
  /opt/pkg/env/active/bin                      /etc/paths.d/10-pmk-global:1  (does not exist)
  /Applications/VMware                         /etc/paths.d/com.vmware.fusion.public:1  (does not exist)

デッドエントリが見つかった場合、終了コード 1 を返します（スクリプトで有用）。

制限事項

• 1行に1つの代入（export EDITOR=vim VISUAL=vim は EDITOR のみ記録）。
• dangling は PATH のような代入や展開を解決しません（export GOPATH=$HOME/go）。
• path の帰属は xtrace の差分に基づきます — エントリを含む最初の代入がそれを主張します（明示的に追加されたのではなく $PATH の展開によって引き継がれた場合でも）。
• 非対応シェル: fish、nu、csh/tcsh、PowerShell。

設計上、読み取り専用

envocabulary は決して unset、rm、またはシェル設定を編集しません。緊急時に使うツールが事態を悪化させるものであってはいけません。クリーンアップしたい場合は、file:line のポインタをコピーして自分で編集してください。clean は stdout に出力するので、リダイレクトは自分で行ってください。