envocabulary

Per ogni variabile nella tua shell corrente, trova il file e la riga che l'ha impostata — o quale sottosistema (direnv, launchd, terminale, SSH, sistema) l'ha iniettata. In più alcuni comandi per file statici per quando la tua configurazione della shell si è sparsa tra N file e backup e hai perso il filo.

L'ho costruito perché continuavo a perdere la stessa ora ogni pochi mesi cercando di capire perché qualche JAVA_HOME o PATH puntava da qualche parte che non mi aspettavo. which conosce i comandi, direnv status conosce direnv, launchctl getenv conosce launchd — nessuno di loro ti dice che ~/.zshrc:42 è l'effettivo scrittore.

Funziona con zsh e bash su macOS, Linux e FreeBSD.

Il momento "ah"

Un grep -r JAVA_HOME ~ mostrerà ogni file che menziona la variabile, ma dall'output non è chiaro quale assegnazione sia attiva nella shell corrente:

$ 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]

Installazione

Comando singolo (rileva OS/arch, posiziona il binario sul tuo $PATH, pulisce Gatekeeper su macOS):

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

Oppure go install github.com/sreckoskocilic/envocabulary/cmd/envocabulary@latest. I binari precompilati e i pacchetti Linux (.deb / .rpm / .apk / .pkg.tar.zst) si trovano nella pagina delle release.

Comandi

Variabili attive (ispeziona la shell in esecuzione):

• scan (predefinito) — stampa tutte le variabili nell'ambiente corrente raggruppate per origine
• explain NOME — stampa l'attribuzione completa per la variabile fornita
• path [NOMEVAR...] — attribuzione per singola voce per variabili di percorso separate da due punti; --check trova voci inesistenti

File statici:

• inventory — elenca tutti i file di configurazione della shell e conta le definizioni per tipo
• catalog — stampa l'intera configurazione della shell unendo tutti i suoi file di configurazione
• dedup — report dei duplicati tra file per export, assign, alias, funzioni
• dangling — elenca le voci dei file di configurazione che non fanno più riferimento a un target valido
• lost — elenca le definizioni uniche presenti solo in file di configurazione orfani/di backup
• report — audit combinato: eliminabili, da revisionare (duplicati con valore cambiato), dangling, file orfani; --html scrive un file .html con timestamp nella directory corrente
• clean [--full] FILE — elenca le righe da rimuovere; con --full, stampa il contenuto pulito completo

Altri:

• -V, --version — stampa versione, commit e data di build

envocabulary <cmd> -h per le opzioni.

L'output di esempio qui sotto usa ~/ per brevità; lo strumento stampa percorsi assoluti ovunque tranne in report.

Un altro esempio: trovare riferimenti interrotti

dangling elenca le voci dei file di configurazione che non fanno più riferimento a un target valido — i residui come JAVA_HOME=/opt/jdk-i-uninstalled e 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)

Un altro esempio: tracciare le voci di PATH

path mostra dove è stata introdotta ogni voce in PATH (o MANPATH, FPATH, ecc.):

$ 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

Le voci non abbinate a nessuna assegnazione di avvio della shell vengono mostrate come inherited.

--check filtra per voci la cui directory non esiste più e le riconduce al file di configurazione da modificare:

$ 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)

Esce con codice 1 quando vengono trovate voci morte (utile negli script).

Limiti

• Una sola assegnazione per riga (export EDITOR=vim VISUAL=vim registra solo EDITOR).
• dangling non risolverà assegnazioni di tipo PATH o espansioni (export GOPATH=$HOME/go).
• L'attribuzione di path si basa sui diff di xtrace — la prima assegnazione che include una voce se la aggiudica, anche se è stata portata avanti tramite espansione di $PATH anziché aggiunta esplicita.
• Shell non supportate: fish, nu, csh/tcsh, PowerShell.

Sola lettura per progettazione

envocabulary non eseguirà mai unset, rm o modificherà la configurazione della shell. Uno strumento di emergenza non dovrebbe essere ciò che peggiora l'emergenza. Se vuoi pulire, copia i puntatori file:riga e modifica tu stesso. clean produce output su stdout; fai tu il redirect.