# Grep

يبحث في محتويات الملفات باستخدام محرك ripgrep. يوفر دعماً كاملاً للتعابير النمطية وفلترة حسب نوع الملف وثلاثة أوضاع إخراج للمفاضلة بين الدقة والاختصار.

## متى يُستخدم

- تحديد كل موقع استدعاء لدالة أو كل مرجع لمعرِّف
- التحقق مما إذا كانت سلسلة أو رسالة خطأ تظهر في أي مكان في قاعدة الشفرة
- عدّ ورودات نمط لقياس الأثر قبل إعادة الهيكلة
- تضييق البحث إلى نوع ملف (`type: "ts"`) أو glob (`glob: "**/*.tsx"`)
- جلب تطابقات ممتدة عبر أسطر مثل تعريفات الـ structs متعددة الأسطر أو كتل JSX باستخدام `multiline: true`

## المعاملات

- `pattern` (سلسلة، مطلوب): التعبير النمطي المراد البحث عنه. يستخدم صياغة ripgrep، لذا تحتاج الأقواس الحرفية إلى تضليل (مثل `interface\{\}` للعثور على `interface{}`).
- `path` (سلسلة، اختياري): ملف أو دليل للبحث. الافتراضي دليل العمل الحالي.
- `glob` (سلسلة، اختياري): مرشح اسم ملف مثل `*.js` أو `*.{ts,tsx}`.
- `type` (سلسلة، اختياري): اختصار نوع الملف مثل `js` أو `py` أو `rust` أو `go`. أكفأ من `glob` للغات القياسية.
- `output_mode` (تعداد، اختياري): `files_with_matches` (الافتراضي، يُعيد المسارات فقط)، أو `content` (يُعيد الأسطر المطابقة)، أو `count` (يُعيد أعداد التطابقات).
- `-i` (قيمة منطقية، اختياري): مطابقة غير حساسة لحالة الأحرف.
- `-n` (قيمة منطقية، اختياري): تضمين أرقام الأسطر في وضع `content`. الافتراضي `true`.
- `-A` (رقم، اختياري): أسطر السياق المعروضة بعد كل تطابق (يتطلب وضع `content`).
- `-B` (رقم، اختياري): أسطر السياق قبل كل تطابق (يتطلب وضع `content`).
- `-C` / `context` (رقم، اختياري): أسطر السياق على جانبي كل تطابق.
- `multiline` (قيمة منطقية، اختياري): السماح للأنماط بامتدادها عبر الأسطر (`.` يطابق `\n`). الافتراضي `false`.
- `head_limit` (رقم، اختياري): حد الأسطر أو مسارات الملفات أو إدخالات العدّ المُعادة. الافتراضي 250؛ مرر `0` لعدم وجود حد (استخدمه باعتدال).
- `offset` (رقم، اختياري): تخطي أول N نتائج قبل تطبيق `head_limit`. الافتراضي `0`.

## أمثلة

### مثال 1: إيجاد جميع مواقع استدعاء دالة
اضبط `pattern: "registerHandler\\("` و`output_mode: "content"` و`-C: 2` لرؤية الأسطر المحيطة بكل استدعاء.

### مثال 2: عدّ التطابقات عبر نوع
اضبط `pattern: "TODO"` و`type: "py"` و`output_mode: "count"` لرؤية إجماليات TODO لكل ملف عبر مصادر Python.

### مثال 3: تطابق بنية متعددة الأسطر
استخدم `pattern: "struct Config \\{[\\s\\S]*?version"` مع `multiline: true` لالتقاط حقل مُعلَن على بُعد عدة أسطر داخل بنية Go.

## ملاحظات

- فضِّل دائماً `Grep` على تشغيل `grep` أو `rg` عبر `Bash`؛ فالأداة مُحسَّنة للأذونات الصحيحة والمخرجات المنظمة.
- وضع الإخراج الافتراضي `files_with_matches` هو الأرخص. انتقل إلى `content` فقط عندما تحتاج إلى رؤية الأسطر نفسها.
- أعلام السياق (`-A`، `-B`، `-C`) تُتجاهل إلا إذا كان `output_mode` هو `content`.
- مجموعات النتائج الكبيرة تستهلك رموز السياق. استخدم `head_limit` أو `offset` أو فلاتر `glob`/`type` أضيق للبقاء مركِّزاً.
- لاكتشاف أسماء الملفات، استخدم `Glob` بدلاً منها؛ وللتحقيقات المفتوحة عبر جولات كثيرة، أرسل `Agent` مع وكيل Explore.
