أوامر Serpl

أوامر واجهة المستخدم النصية الشاملة Serpl لعمليات البحث والاستبدال على مستوى المشروع.

التثبيت

الأمر	الوصف
cargo install serpl	التثبيت عبر Cargo (Rust)
brew install serpl	التثبيت عبر Homebrew (macOS)
nix-env -i serpl	التثبيت عبر Nix
pacman -S serpl	التثبيت على Arch Linux
التحميل من GitHub Releases	الملفات الثنائية المجمعة متاحة
serpl --version	عرض إصدار Serpl

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

الأمر	الوصف
serpl	تشغيل Serpl في الدليل الحالي
serpl --search-text "oldFunc"	التشغيل مع مصطلح بحث معبأ مسبقاً
serpl --replace-text "newFunc"	التشغيل مع بديل معبأ مسبقاً
serpl --search-path ./src	البحث في دليل محدد
serpl --hidden	تضمين الملفات المخفية في البحث
serpl --ignore-case	بحث غير حساس لحالة الأحرف

مفاتيح التنقل

الاختصار	الوصف
j	النزول في قائمة النتائج
k	الصعود في قائمة النتائج
g	الانتقال إلى أول نتيجة
G	الانتقال إلى آخر نتيجة
/	البحث في قائمة النتائج
Enter	تحديد/تأكيد الإجراء
Escape	الإلغاء/العودة للخلف
q	الخروج من Serpl

تبديل الأوضاع

الاختصار	الوصف
Tab	التبديل بين حقول البحث والاستبدال
Ctrl + N	التبديل بين أوضاع البحث والاستبدال
Ctrl + B	فتح حوار المساعدة
Ctrl + C	الخروج من التطبيق

عمليات البحث

الاختصار	الوصف
اكتب في حقل البحث	البحث المباشر في جميع الملفات
Ctrl + N	تبديل وضع البحث
وضع حساس لحالة الأحرف	مطابقة حالة الأحرف بالضبط
وضع غير حساس لحالة الأحرف	تجاهل الاختلافات في الحالة
وضع Regex	استخدام التعبيرات العادية
وضع AST Grep	البحث الهيكلي عن الأكواد

عمليات الاستبدال

الاختصار	الوصف
Ctrl + O	معالجة الاستبدال لجميع الملفات
d	حذف الملف أو السطر المحدد من النتائج
استبدال بسيط	استبدال جميع الحالات مباشرة
استبدال مع الحفاظ على الحالة	الحفاظ على نمط الحالة الأصلي
استبدال AST Grep	استبدال الأكواد الذي يفهم التراكيب

أوضاع الاستبدال

الوضع	الوصف
البسيط	استبدال نص مباشر
الحفاظ على الحالة	مطابقة نمط الحالة للنص الأصلي
AST Grep	استبدال يفهم شجرة الأكواد

أوضاع البحث

الوضع	الوصف
سلسلة ثابتة	مطابقة النص الحرفي
Regex	مطابقة التعبير العادي
AST Grep	مطابقة نمط الأكواد الهيكلي

عمليات الملفات

الاختصار	الوصف
d	إزالة الملف/السطر من النتائج (تخطي)
Ctrl + O	تطبيق الاستبدالات على جميع الملفات المتبقية
مراجعة التغييرات لكل ملف	عرض معاينة قبل التطبيق
التراجع غير متاح	التغييرات دائمة - استخدم Git

التكوين

الإعداد	الوصف
~/.config/serpl/config.json	موقع ملف التكوين
ربط مفاتيح مخصصة	استبدال الاختصارات الافتراضية
وضع البحث الافتراضي	تعيين وضع البحث المفضل
وضع الاستبدال الافتراضي	تعيين وضع الاستبدال المفضل
مرشحات نمط الملف	تكوين الملفات المراد تضمينها
أنماط التجاهل	تكوين الملفات المراد استبعادها

مثال على التكوين

{
  "key_bindings": {
    "quit": "q",
    "navigate_up": "k",
    "navigate_down": "j",
    "go_to_top": "g",
    "go_to_bottom": "G",
    "delete": "d",
    "process_replace": "Ctrl+o",
    "toggle_help": "Ctrl+b",
    "search_in_list": "/"
  },
  "search_mode": "fixed_string",
  "replace_mode": "simple"
}

سير العمل الشامل

سير العمل	الوصف
إعادة تسمية المتغير	البحث عن الاسم القديم → الاستبدال بالاسم الجديد
تحديث مسارات الاستيراد	البحث عن المسار القديم → الاستبدال بالمسار الجديد
ترحيل استدعاءات API	البحث عن المتقادم → الاستبدال بـ API الجديد
إصلاح الأخطاء الإملائية	البحث عن الخطأ → الاستبدال بالصحيح
تحديث قيم التكوين	البحث عن القيمة القديمة → الاستبدال بالقيمة الجديدة

التكامل مع Git

سير العمل	الوصف
git diff بعد serpl	مراجعة جميع التغييرات المجراة
git stash قبل serpl	حفظ العمل الحالي أولاً
git checkout -- . للتراجع	استرجاع جميع التغييرات إذا لزم الأمر
العمل في فرع	عزل تغييرات البحث والاستبدال
git add -p بعد serpl	مرحلة التغييرات بانتقائية

مقارنة مع البدائل

الميزة	Serpl	sed	VS Code
معاينة تفاعلية	نعم	لا	نعم
واجهة TUI	نعم	لا	GUI
الحفاظ على الحالة	نعم	يدوي	نعم
AST Grep	نعم	لا	امتداد
يعمل عبر SSH	نعم	نعم	لا
دعم Regex	نعم	نعم	نعم

نصائح وأفضل الممارسات

النصيحة	الوصف
استخدم دائماً Git	قم بالالتزام قبل تشغيل الاستبدالات
معاينة قبل التطبيق	راجع كل تغيير في TUI
استخدم AST Grep للأكواد	المطابقة الهيكلية تتجنب المطابقات الخاطئة
استخدم الحفاظ على الحالة	الحفاظ على camelCase و PascalCase وما إلى ذلك
إزالة المطابقات الكاذبة	استخدم d لتخطي المطابقات غير المرغوبة
البحث في مسارات محددة	استخدم --search-path لتضييق النطاق
فحص الملفات المخفية	استخدم علم --hidden عند الحاجة