Zoxide

أمر cd أذكى يتعلم عاداتك باستخدام خوارزمية التكرار-الحداثة للتنقل السريع بين المجلدات عبر الصدفات المختلفة.

التثبيت

مديرو الحزم

أمر	وصف
`brew install zoxide`	التثبيت على macOS باستخدام Homebrew
`cargo install zoxide --locked`	التثبيت من crates.io
`apt install zoxide`	التثبيت على Debian/Ubuntu
`pacman -S zoxide`	التثبيت على Arch Linux
`dnf install zoxide`	التثبيت على Fedora
`scoop install zoxide`	التثبيت على Windows باستخدام Scoop
`winget install ajeetdsouza.zoxide`	التثبيت على Windows باستخدام winget
`nix-env -i zoxide`	التثبيت على NixOS
`conda install -c conda-forge zoxide`	التثبيت باستخدام Conda
`curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh`	التثبيت عبر سكريبت الصدفة

تهيئة الصدفة

أمر	وصف
`eval "$(zoxide init bash)"`	التهيئة لـ Bash (أضف إلى .bashrc)
`eval "$(zoxide init zsh)"`	التهيئة لـ Zsh (أضف إلى .zshrc)
`zoxide init fish \| source`	التهيئة لـ Fish (أضف إلى config.fish)
`Invoke-Expression (& { (zoxide init powershell) })`	التهيئة لـ PowerShell
`zoxide init nushell \| save -f ~/.zoxide.nu`	التهيئة لـ Nushell
`eval "$(zoxide init elvish)"`	التهيئة لـ Elvish
`eval (zoxide init xonsh)`	التهيئة لـ Xonsh

أمثلة تكوين الصدفة

# Bash — أضف إلى ~/.bashrc
eval "$(zoxide init bash)"

# Zsh — أضف إلى ~/.zshrc
eval "$(zoxide init zsh)"

# Fish — أضف إلى ~/.config/fish/config.fish
zoxide init fish | source

# PowerShell — أضف إلى $PROFILE
Invoke-Expression (& { (zoxide init powershell | Out-String) })

# Nushell — أضف إلى env.nu
zoxide init nushell | save -f ~/.zoxide.nu
source ~/.zoxide.nu

الاستخدام الأساسي

التنقل

أمر	وصف
`z foo`	الانتقال إلى المجلد الأعلى تصنيفاً المطابق لـ “foo”
`z foo bar`	الانتقال إلى المجلد المطابق لكل من “foo” و “bar”
`z ~/projects`	الانتقال إلى مسار محدد (مثل cd)
`z ..`	الانتقال إلى المجلد الأب
`z -`	الانتقال إلى المجلد السابق
`z`	الانتقال إلى المجلد الرئيسي (بدون معاملات)
`zi`	اختيار تفاعلي باستخدام fzf
`zi foo`	اختيار تفاعلي مع تصفية مسبقة بـ “foo”
`z foo/`	الانتقال إلى مجلد فرعي (شرطة مائلة لاحقة)

أمثلة الاستخدام

# بعد زيارة المجلدات، يتعلمها zoxide
cd ~/projects/myapp          # تعليم zoxide عن هذا المسار
cd ~/documents/reports       # تعليم zoxide عن هذا المسار
cd /var/log/nginx            # تعليم zoxide عن هذا المسار

# لاحقاً، انتقل بمطابقات جزئية
z myapp                      # ينتقل إلى ~/projects/myapp
z reports                    # ينتقل إلى ~/documents/reports
z nginx                      # ينتقل إلى /var/log/nginx

# كلمات مفتاحية متعددة تضيّق المطابقة
z proj myapp                 # يطابق ~/projects/myapp تحديداً
z doc rep                    # يطابق ~/documents/reports

صيغة الاستعلام

قواعد المطابقة

أمر	وصف
`z proj`	مطابقة أي مجلد يحتوي على “proj”
`z proj rust`	مطابقة مجلد يحتوي على كل من “proj” و “rust”
`z /home/user/docs`	استخدام المسار المطلق مباشرة
`z docs/`	مطابقة وتفضيل مجلد فرعي باسم “docs”
الكلمات المفتاحية تطابق مكونات المسار	”proj” يطابق `/home/user/projects`
الكلمة المفتاحية الأخيرة يمكنها مطابقة البادئة	`z pr` يطابق `projects`
الكلمات المفتاحية المتعددة تُطابق بالعامل AND	يجب أن تظهر جميعها في المسار
المطابقة غير حساسة لحالة الأحرف	`z PROJ` يطابق `projects`

خوارزمية التكرار-الحداثة

مفهوم	وصف
التكرار-الحداثة = التكرار + الحداثة	نتيجة تعتمد على عدد وحداثة الزيارات
الزيارات الحديثة تحصل على نتيجة أعلى	المجلدات المزارة اليوم تحصل على نتيجة أعلى من الأسبوع الماضي
المجلدات المزارة بشكل متكرر تحتل مرتبة أعلى	الاستخدام المنتظم يزيد النتيجة بمرور الوقت
النتائج تتناقص بمرور الوقت	المجلدات غير المستخدمة تفقد تصنيفها تدريجياً
قاعدة البيانات تحذف تلقائياً النتائج المنخفضة	الإدخالات القديمة غير المستخدمة تُزال تلقائياً
الحد الأقصى للإدخالات يُتحكم به بـ `_ZO_MAXAGE`	الافتراضي: 10,000 إدخال

الاختيار التفاعلي

أمر	وصف
`zi`	فتح fzf مع جميع المجلدات المتتبعة
`zi query`	فتح fzf مع تصفية مسبقة بالاستعلام
`↑ / ↓` في fzf	التنقل بين النتائج
`Enter` في fzf	الاختيار والانتقال إلى المجلد
`Escape` في fzf	إلغاء الاختيار
الكتابة في fzf للتصفية	تضييق النتائج أكثر
يتطلب تثبيت `fzf`	ثبّت fzf للوضع التفاعلي
`Tab` في fzf	تبديل الاختيار (وضع الاختيار المتعدد)

مثال تفاعلي

# فتح الباحث الضبابي التفاعلي مع جميع المجلدات المتتبعة
zi

# تصفية مسبقة للمجلدات التي تحتوي على "project"
zi project

# تنسيق العرض في fzf يظهر النتائج:
#   3.50   /home/user/projects/myapp
#   2.10   /home/user/projects/api
#   1.20   /var/www/project-site

تكامل الصدفة

استبدال cd

أمر	وصف
`eval "$(zoxide init bash --cmd cd)"`	استبدال cd بـ zoxide في Bash
`eval "$(zoxide init zsh --cmd cd)"`	استبدال cd بـ zoxide في Zsh
`--cmd cd` يستبدل أمر `cd`	يجعل cd يستخدم zoxide (cd, cdi)
`--cmd j` ينشئ `j` و `ji`	استخدام أسماء أوامر مخصصة
الافتراضي ينشئ `z` و `zi`	أوامر zoxide القياسية

تكوين الخطاف

أمر	وصف
`--hook pwd`	تحديث قاعدة البيانات عند تغيير المجلد (الافتراضي)
`--hook prompt`	تحديث قاعدة البيانات عند كل سطر أوامر
`--hook none`	تعطيل التتبع التلقائي

التكامل مع أدوات أخرى

# استبدال cd في Bash بـ zoxide
eval "$(zoxide init bash --cmd cd)"
# الآن 'cd' يستخدم zoxide، 'cdi' يفتح التفاعلي

# استخدام اسم أمر مخصص
eval "$(zoxide init zsh --cmd j)"
# الآن 'j foo' ينتقل، 'ji' يفتح التفاعلي

# الدمج مع fzf لتجربة محسنة
export _ZO_FZF_OPTS="--height 40% --reverse --border"

إدارة قاعدة البيانات

استعلام قاعدة البيانات

أمر	وصف
`zoxide query foo`	عرض أفضل مطابقة بدون الانتقال
`zoxide query foo --list`	عرض جميع المطابقات مع النتائج
`zoxide query foo --score`	عرض المطابقات مع نتائج التكرار-الحداثة
`zoxide query --all`	عرض قاعدة البيانات بالكامل
`zoxide query --all --score`	عرض قاعدة البيانات مع النتائج
`zoxide query --exclude /path`	استبعاد مسار محدد من النتائج
`zoxide query --list \| head -20`	أعلى 20 مجلد

إدارة الإدخالات

أمر	وصف
`zoxide add /path/to/dir`	إضافة مجلد يدوياً إلى قاعدة البيانات
`zoxide remove /path/to/dir`	إزالة مجلد من قاعدة البيانات
`zoxide edit`	فتح قاعدة البيانات في $EDITOR (تفاعلي)
قاعدة البيانات مخزنة في `$_ZO_DATA_DIR/db.zo`	موقع قاعدة البيانات الافتراضي

أمثلة قاعدة البيانات

# التحقق مما سيطابقه zoxide
zoxide query project --list --score
# المخرجات:
#    12.00  /home/user/projects/webapp
#     8.50  /home/user/projects/api
#     3.20  /home/user/old-project

# ملء قاعدة البيانات يدوياً للأجهزة الجديدة
zoxide add ~/projects/webapp
zoxide add ~/projects/api
zoxide add ~/.config/nvim

# إزالة الإدخالات القديمة (المجلدات المحذوفة)
zoxide query --all | while read -r dir; do
  [ -d "$dir" ] || zoxide remove "$dir"
done

# تصدير قاعدة البيانات للنسخ الاحتياطي
zoxide query --all --score > zoxide-backup.txt

الاستيراد من أدوات أخرى

أمر	وصف
`zoxide import --from z path/to/.z`	الاستيراد من قاعدة بيانات z.sh
`zoxide import --from autojump path/to/autojump.txt`	الاستيراد من قاعدة بيانات autojump
`zoxide import --merge --from z path/to/.z`	استيراد مع دمج (الاحتفاظ بالإدخالات الموجودة)
`zoxide import --from z --merge ~/.z`	استيراد z.sh الشائع

أمثلة الترحيل

# الترحيل من z.sh (الأكثر شيوعاً)
zoxide import --from z ~/.z

# الترحيل من autojump
zoxide import --from autojump ~/.local/share/autojump/autojump.txt

# الدمج مع قاعدة البيانات الموجودة (بدون الكتابة فوق)
zoxide import --merge --from z ~/.z

# بعد الاستيراد، تحقق
zoxide query --all --score | head -20

متغيرات البيئة

أمر	وصف
`export _ZO_DATA_DIR="$HOME/.local/share/zoxide"`	تعيين مجلد قاعدة البيانات
`export _ZO_ECHO=1`	طباعة المجلد المطابق قبل الانتقال
`export _ZO_EXCLUDE_DIRS="/tmp/:/private/"`	استبعاد مجلدات من التتبع
`export _ZO_FZF_OPTS="--height 40%"`	خيارات fzf مخصصة لـ zi
`export _ZO_MAXAGE=10000`	تعيين الحد الأقصى لإدخالات قاعدة البيانات
`export _ZO_RESOLVE_SYMLINKS=1`	حل الروابط الرمزية قبل التخزين

مثال التكوين

# ~/.bashrc أو ~/.zshrc — تكوين zoxide الكامل

# تعيين مجلد بيانات مخصص
export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

# طباعة المجلد المطابق قبل الانتقال
export _ZO_ECHO=1

# استبعاد المجلدات المؤقتة ومجلدات النظام
export _ZO_EXCLUDE_DIRS="$HOME:$HOME/Downloads:/tmp/*:/private/*"

# تخصيص مظهر fzf للوضع التفاعلي
export _ZO_FZF_OPTS="
  --height 40%
  --layout reverse
  --border rounded
  --preview 'ls -la {2..}'
  --preview-window right:40%
"

# الحد الأقصى للإدخالات قبل التقليم (الافتراضي: 10000)
export _ZO_MAXAGE=10000

# حل الروابط الرمزية إلى مسارات قياسية
export _ZO_RESOLVE_SYMLINKS=1

# تهيئة zoxide (يجب أن تكون بعد التصديرات)
eval "$(zoxide init zsh)"

الإكمال التلقائي ودعم Tab

أمر	وصف
`z <Tab>`	الإكمال التلقائي من المجلدات المتتبعة
`z foo<Tab>`	إكمال المجلدات المطابقة
إكمال Bash عبر `zoxide init`	تلقائي مع تهيئة الصدفة
إكمال Zsh عبر `zoxide init`	تلقائي مع تهيئة الصدفة
إكمال Fish عبر `zoxide init`	تلقائي مع تهيئة الصدفة

أفضل الممارسات

دع zoxide يتعلم بشكل طبيعي — استخدم صدفتك بشكل عادي وسيبني zoxide قاعدة بياناته من عاداتك. لا تحاول ملء كل مجلد يدوياً.
استخدم كلمتين مفتاحيتين للدقة — عندما تتطابق عدة مجلدات، أضف كلمة مفتاحية ثانية: z proj api أكثر دقة من z api وحده.
استخدم الشرطة المائلة اللاحقة للمجلدات الفرعية — z foo/ يفضل المجلدات الفرعية للمجلد الحالي المسماة “foo”، بينما z foo يبحث في قاعدة البيانات بالكامل.
استبدل cd للتعلم الأقصى — استخدم --cmd cd في تهيئة صدفتك حتى يغذي كل تغيير مجلد zoxide، وليس فقط عندما تتذكر استخدام z.
كوّن الاستثناءات مبكراً — عيّن _ZO_EXCLUDE_DIRS لتخطي المجلدات المؤقتة ومجلدات البناء ومسارات node_modules التي تلوث النتائج.
استخدم zi للانتقالات الغامضة — عندما لا تكون متأكداً من المجلد الذي سيتطابق، استخدم zi (تفاعلي) لمعاينة واختيار من المرشحين.
رحّل البيانات الموجودة — إذا كنت تنتقل من z.sh أو autojump أو fasd، استورد قاعدة بياناتك بـ zoxide import للبدء بذاكرة مؤقتة دافئة.
نظّف الإدخالات القديمة — أزل بشكل دوري الإدخالات للمجلدات المحذوفة باستخدام zoxide edit أو سكريبت تنظيف للحفاظ على صلة النتائج.
انسخ قاعدة بياناتك احتياطياً — صدّر بـ zoxide query --all --score قبل إعادة تثبيت نظام التشغيل أو ترحيل الأجهزة.
خصص مظهر fzf — عيّن _ZO_FZF_OPTS مع --preview 'ls {2..}' لعرض محتويات المجلد في المنتقي التفاعلي.