envocabulary

Para cada variável no seu shell atual, encontre o arquivo e a linha que a definiu — ou qual subsistema (direnv, launchd, terminal, SSH, system) a injetou. Além de alguns comandos de arquivos estáticos para quando a configuração do seu shell se espalhou por N arquivos e backups e você perdeu o fio da meada.

Eu construí isto porque eu perdia a mesma hora a cada poucos meses rastreando por que algum JAVA_HOME ou PATH estava apontando para algum lugar que eu não esperava. which conhece comandos, direnv status conhece direnv, launchctl getenv conhece launchd — nenhum deles diz que ~/.zshrc:42 é o verdadeiro autor.

Funciona com zsh e bash no macOS, Linux e FreeBSD.

O momento "ah"

Um grep -r JAVA_HOME ~ mostrará todos os arquivos que mencionam a variável, mas não fica claro pela saída qual atribuição está ativa no shell atual:

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

Instalação

Instalação em uma linha (detecta SO/arquitetura, coloca o binário no seu $PATH, limpa o Gatekeeper no macOS):

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

Ou go install github.com/sreckoskocilic/envocabulary/cmd/envocabulary@latest. Binários pré-compilados e pacotes Linux (.deb / .rpm / .apk / .pkg.tar.zst) estão na página de releases.

Comandos

Env ao vivo (inspeciona o seu shell em execução):

• scan (padrão) — imprime todas as variáveis no ambiente atual agrupadas por origem
• explain NAME — imprime a atribuição completa para a variável fornecida
• path [VARNAME...] — atribuição por entrada para variáveis de caminho separadas por dois-pontos; --check encontra entradas mortas

Arquivos estáticos:

• inventory — lista todos os arquivos de configuração do shell e conta definições por tipo
• catalog — imprime toda a configuração do shell mesclando todos os seus arquivos de configuração
• dedup — relatório de duplicatas entre arquivos para exports, atribuições, aliases e funções
• dangling — lista entradas de arquivos de configuração que não referenciam mais um alvo válido
• lost — lista definições exclusivas de arquivos de configuração órfãos/backup
• report — auditoria combinada: seguro para excluir, revisar (duplicatas com valor alterado), dangling, arquivos órfãos; --html grava um arquivo .html com timestamp no diretório atual
• clean [--full] FILE — lista linhas a serem removidas; com --full, imprime o conteúdo completo já limpo

Outros:

• -V, --version — imprime versão, commit e data de build

Use envocabulary <cmd> -h para ver as flags.

A saída de exemplo abaixo usa ~/ por brevidade; a ferramenta imprime caminhos absolutos em todos os lugares exceto report.

Outro exemplo: encontrando referências quebradas

dangling lista entradas de arquivos de configuração que não referenciam mais um alvo válido — o tipo de resíduos como 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)

Outro exemplo: rastreando entradas do PATH

path mostra onde cada entrada em PATH (ou MANPATH, FPATH, etc.) foi introduzida:

$ 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

Entradas que não correspondem a nenhuma atribuição de inicialização do shell são exibidas como inherited.

--check filtra as entradas cujo diretório não existe mais e as rastreia de volta ao arquivo de configuração a ser editado:

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

Encerra com o código 1 quando entradas mortas são encontradas (útil em scripts).

Limitações

• Uma atribuição por linha (export EDITOR=vim VISUAL=vim registra apenas EDITOR).
• dangling não resolve atribuições ou expansões do tipo PATH (export GOPATH=$HOME/go).
• A atribuição do path é baseada em diffs de xtrace — a primeira atribuição que inclui uma entrada fica com ela, mesmo que ela tenha sido propagada via expansão de $PATH em vez de adicionada explicitamente.
• Shells sem suporte: fish, nu, csh/tcsh, PowerShell.

Somente leitura por design

envocabulary nunca executará unset, rm nem editará a configuração do seu shell. Uma ferramenta de emergência não deveria ser a coisa que piora a emergência. Se você quiser limpar as coisas, copie os ponteiros file:line e faça as edições você mesmo. clean envia a saída para o stdout; você faz o redirecionamento.