envocabulary

現在のシェルにあるすべての変数について、それを設定したファイルと行、あるいはどのサブシステム（direnv、launchd、ターミナル、SSH、システム）が注入したのかを特定します。さらに、シェル設定が N 個のファイルとバックアップに散らばって見失ったときのための、静的ファイル向けコマンドもいくつか用意しています。

これを作ったのは、数か月ごとに同じ 1 時間を無駄にして、なぜ JAVA_HOME や PATH が予想外の場所を指しているのかを追いかけていたからです。which はコマンドを知り、direnv status は direnv を知り、launchctl getenv は launchd を知っています。しかし、どれも ~/.zshrc:42 が実際の書き込み元だとは教えてくれません。

macOS、Linux、FreeBSD 上の zsh と bash で動作します。以下のサンプル出力では簡潔さのために ~/ を使っていますが、ツールは report を除いてすべて絶対パスを表示します。

「あっ」となる瞬間

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]

eval "$(brew shellenv)"、eval "$(pyenv init -)" などで設定された変数は、eval の行を指します。生成されたコードには独自の行がありません。エディタで開けるのは eval のほうです。

インストール

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

このスクリプトは OS とアーキテクチャを検出し、リリースアーカイブをダウンロードし、sha256 チェックサムを検証し、cosign がインストールされていれば cosign 署名も検証します。/usr/local/bin が書き込み可能ならそこに、そうでなければ ~/.local/bin にインストールし、そのディレクトリが $PATH にない場合は警告します。macOS では Gatekeeper の隔離フラグも解除します。

オプション: sh -s -- --version v1.0.4 でバージョンを固定、--bin-dir DIR でインストール先を指定できます。

または go install github.com/sreckoskocilic/envocabulary/cmd/envocabulary@latest。go install によるビルドでは --version が dev を報告することに注意してください。バージョン、コミット、ビルド日時が含まれるのはリリースバイナリだけです。

ビルド済みバイナリと Linux パッケージ（.deb / .rpm / .apk / .pkg.tar.zst）はリリースページにあります。

コマンド

ライブ環境（実行中のシェルを読み取る）:

scan (デフォルト) — 現在の環境のすべての変数を origin ごとにグループ化して表示
explain NAME — 1 つの変数の完全な帰属情報
path [VARNAME...] — コロン区切りのパス変数のエントリごとの帰属情報。--check は無効なエントリを検出
inventory — $HOME にあるシェル設定ファイル（正規のものと .zshrc.bak のようなバックアップ版）を一覧表示し、型ごとに定義をカウント
catalog — それらのファイルをシェルが読み込む順に連結して表示
dedup — exports、assigns、aliases、functions の重複レポート（ファイル内およびファイル間）
dangling — 対象がもう存在しない設定エントリを一覧表示。見つかった場合は終了コード 1
lost — 孤立/バックアップファイルにのみ存在する定義を一覧表示
report — 統合監査: 削除しても安全なもの、要確認（値が異なる重複、およびすべての重複関数）、dangling、孤立ファイル。--html はタイムスタンプ付きの .html ファイルをカレントディレクトリに書き出す
clean [--full] FILE — 削除されるコメント行を一覧表示。--full を付けるとクリーンアップ後の内容を表示

その他:

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

フラグについては envocabulary <cmd> -h を参照してください。

終了コード: 成功時は 0、実行時エラーまたは dangling / path --check が何かを見つけた場合は 1、使用法エラーの場合は 2。

壊れた参照の検出

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:6
  /opt/homebrew/sbin      ~/.zprofile:6
  /usr/local/bin          /etc/zprofile:11
  /usr/bin                inherited
  /bin                    inherited
  ~/.cargo/bin            ~/.zshrc:22

シェル起動時の代入に一致しないエントリは inherited として表示されます。これには常に /usr/bin、/bin、/usr/sbin、/sbin が含まれます。これらはトレーサーが開始するシードであり、ファイルが追加したものではありません。

--check はディレクトリがもう存在しないエントリに絞り込み、ドットファイルと /etc/paths.d に対してソースを再解決するので、編集すべき行を指し示します:

$ 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 のみを記録します。
静的コマンドは $HOME にある正規のドットファイル（.zshenv、.zprofile、.zshrc、.zlogin、.zlogout、.bashrc、.bash_profile、.profile）とその .bak/.old 形式の変種のみを対象とします。$ZDOTDIR、~/.config/zsh、/etc、または source したファイルは追跡しません。
dangling は PATH 風の値と展開を含むもの（export GOPATH=$HOME/go）をスキップします。これらは静的に解決できません。
path の帰属は xtrace の差分に基づきます。エントリを含む最初の代入がそれを主張します。たとえ $PATH 展開経由で引き継がれたもので、明示的に追加されたわけでなくても同様です。
bash では、eval を通じて実行されたコードは eval の行とオフセットを報告します。bash には zsh のような eval 本体のマーカーがありません。
未対応のシェル: fish、nu、csh/tcsh、PowerShell。

設計上読み取り専用

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

envocabulary v1.0.5

カテゴリ