envocabulary

Para cada variable en tu shell actual, encuentra el archivo y la línea que la definió — o qué subsistema (direnv, launchd, terminal, SSH, system) la inyectó. Además, unos pocos comandos de archivos estáticos para el momento en que tu configuración de shell se ha extendido por N archivos y copias de seguridad y has perdido el hilo.

Construí esto porque seguía perdiendo la misma hora cada pocos meses rastreando por qué algún JAVA_HOME o PATH apuntaba a donde no esperaba. which conoce los comandos, direnv status conoce direnv, launchctl getenv conoce launchd — ninguno de ellos te dice que ~/.zshrc:42 es quien realmente lo escribe.

Funciona con zsh y bash en macOS, Linux y FreeBSD.

El momento "ah"

Un grep -r JAVA_HOME ~ mostrará todos los archivos que mencionan la variable, pero no queda claro en la salida qué asignación está activa en el shell actual:

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

Instalación

Una línea (detecta SO/arquitectura, coloca el binario en tu $PATH, omite Gatekeeper en macOS):

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

O go install github.com/sreckoskocilic/envocabulary/cmd/envocabulary@latest. Los binarios precompilados y los paquetes de Linux (.deb / .rpm / .apk / .pkg.tar.zst) están en la página de releases.

Comandos

Entorno en vivo (inspecciona tu shell en ejecución):

scan (predeterminado) — imprime todas las variables del entorno actual agrupadas por origen
explain NAME — imprime la atribución completa de la variable proporcionada
path [VARNAME...] — atribución por entrada para variables de ruta separadas por dos puntos; --check encuentra entradas muertas

Archivos estáticos:

inventory — enumera todos los archivos de configuración del shell y cuenta las definiciones por tipo
catalog — imprime toda la configuración del shell fusionando todos sus archivos de configuración
dedup — informe de duplicados entre archivos para exports, asignaciones, alias y funciones
dangling — enumera las entradas de los archivos de configuración que ya no referencian un objetivo válido
lost — enumera las definiciones exclusivas de archivos de configuración huérfanos o de respaldo
report — auditoría combinada: seguros de eliminar, revisión (duplicados con valor cambiado), colgantes, archivos huérfanos; --html escribe un archivo .html con marca de tiempo en el directorio actual
clean [--full] FILE — enumera las líneas a eliminar; con --full, imprime el contenido limpio completo

Otros:

-V, --version — imprime la versión, el commit y la fecha de compilación

envocabulary <cmd> -h para las opciones.

Los ejemplos de salida a continuación usan ~/ por brevedad; la herramienta imprime rutas absolutas en todas partes excepto en report.

Otro ejemplo: encontrar referencias rotas

dangling enumera las entradas de los archivos de configuración que ya no referencian un objetivo válido — el tipo de restos como JAVA_HOME=/opt/jdk-i-uninstalled y 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)

Otro ejemplo: rastrear entradas de PATH

path muestra dónde se introdujo cada entrada en PATH (o MANPATH, FPATH, etc.):

$ 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

Las entradas que no coinciden con ninguna asignación de inicio del shell se muestran como inherited.

--check filtra las entradas cuyo directorio ya no existe y las rastrea hasta el archivo de configuración que se debe editar:

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

Sale con 1 cuando se encuentran entradas muertas (útil en scripts).

Limitaciones

Una asignación por línea (export EDITOR=vim VISUAL=vim registra solo EDITOR).
dangling no resolverá asignaciones ni expansiones similares a PATH (export GOPATH=$HOME/go).
La atribución de path se basa en diffs de xtrace — la primera asignación que incluye una entrada se la adjudica, incluso si se arrastró mediante la expansión de $PATH en lugar de añadirse explícitamente.
Shells no soportados: fish, nu, csh/tcsh, PowerShell.

Solo lectura por diseño

envocabulary nunca hará unset, rm ni editará tu configuración del shell. Una herramienta de emergencia no debería ser lo que empeore la emergencia. Si quieres limpiar cosas, copia los punteros file:line y haz las ediciones tú mismo. clean escribe en stdout; el redireccionamiento lo haces tú.

envocabulary v1.0.4

Categorías