envocabulary

لكل متغير في شلتك الحالية، ابحث عن الملف والسطر الذي قام بتعيينه — أو أي نظام فرعي (direnv, launchd, terminal, SSH, system) قد حقنه. بالإضافة إلى بعض الأوامر للملفات الثابتة للحظة التي تنتشر فيها إعدادات شلتك عبر N من الملفات والنسخ الاحتياطية وقد فقدت المسار.

بنيت هذه الأداة لأنني كنت أفقد نفس الساعة كل بضعة أشهر في تتبع سبب إشارة بعض JAVA_HOME أو PATH إلى مكان لم أكن أتوقعه. which يعرف الأوامر، direnv status يعرف direnv، launchctl getenv يعرف launchd — لا يخبرك أي منها أن ~/.zshrc:42 هو الكاتب الفعلي.

تعمل مع zsh و bash على macOS و Linux و FreeBSD.

لحظة "آه"

أمر 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]

تثبيت

سطر واحد (يكشف نظام التشغيل/المعمارية، ويضع الثنائي في $PATH الخاص بك، ويمسح Gatekeeper على macOS):

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

أو go install github.com/sreckoskocilic/envocabulary/cmd/envocabulary@latest. الثنائيات المبنية مسبقًا وحزم لينكس (.deb / .rpm / .apk / .pkg.tar.zst) موجودة في صفحة الإصدارات.

الأوامر

البيئة الحية (تفحص شلتك الجارية):

• scan (الافتراضي) — يطبع جميع المتغيرات في البيئة الحالية مجمعة حسب المصدر
• explain NAME — يطبع الإسناد الكامل للمتغير المقدم
• path [VARNAME...] — إسناد لكل مدخل لمتغيرات المسار المفصولة بنقطتين؛ --check يجد المدخلات الميتة

الملفات الثابتة:

• inventory — يسرد جميع ملفات إعدادات الشلة ويحسب التعريفات حسب النوع
• catalog — يطبع إعدادات الشلة بأكملها بدمج جميع ملفات الإعدادات
• dedup — تقرير التكرار عبر الملفات للـ exports، assigns، aliases، functions
• dangling — يسرد مدخلات ملف الإعدادات التي لم تعد تشير إلى هدف صالح
• lost — يسرد التعريفات الفريدة في ملفات الإعدادات اليتيمة/النسخ الاحتياطية
• report — تدقيق مشترك: آمن للحذف، مراجعة (تكرارات بقيمة متغيرة)، معلقة، ملفات يتيمة؛ --html يكتب ملف .html مختومًا بالوقت في الدليل الحالي
• clean [--full] FILE — يسطر الأسطر المراد إزالتها؛ مع --full، يطبع المحتوى المنظف بالكامل

أخرى:

• -V، --version — طباعة الإصدار، الالتزام (commit)، وتاريخ البناء

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 عند العثور على مدخلات ميتة (مفيد في السكربتات).

الحدود

• تعيين واحد لكل سطر (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؛ أنت تقوم بالتوجيه.