متجوّل الملفات

عرض بتنسيق Markdown التعديل على GitHub التوثيق في d105217

يبدأ كل نمط من أنماط Greph (النص وAST وإعادة الكتابة والنص المفهرس وAST المفهرس وAST المخزّن مؤقتًا وغلاف rg وغلاف sg) باجتياز شجرة الملفات وإنشاء Greph\Walker\FileList. المتجوّل مشترك، لذا تنطبق الرايات والسلوكيات نفسها في كل الأنماط.

السلوك الافتراضي

افتراضيًا، يقوم المتجوّل بما يلي:

يتوغّل في كل مجلد ضمن المسارات المطلوبة.
يلتزم بقواعد .gitignore و.grephignore على كل المستويات، بما في ذلك التجاوزات المتداخلة والاستثناءات.
يتخطى مجلد .git.
يتخطى الملفات والمجلدات المخفية (كل ما يبدأ بـ .).
يتخطى الملفات الثنائية (يكتشفها عبر بايتات الصفر في أول 512 بايت من الملف).
يتخطى الملفات التي يتجاوز حجمها 10 MiB.
لا يتبع الروابط الرمزية.

رايات التجاوز

الراية	التأثير
`--no-ignore`	التوقف عن الالتزام بـ `.gitignore` و`.grephignore`
`--hidden`	تضمين الملفات والمجلدات المخفية
`--type NAME`	تضمين الملفات المطابقة للاسم المستعار للنوع فقط
`--type-not NAME`	استبعاد الملفات المطابقة للاسم المستعار للنوع
`--glob GLOB`	تضمين الملفات التي تطابق مساراتها GLOB فقط. يمكن تكرارها.

تتوفر الخيارات نفسها للاستخدام البرمجي عبر Greph\Walker\WalkOptions.

PHP

use Greph\Greph;
use Greph\Walker\FileTypeFilter;
use Greph\Walker\WalkOptions;

$files = Greph::walk('src', new WalkOptions(
    respectIgnore: false,
    includeHidden: true,
    fileTypeFilter: new FileTypeFilter(['php']),
    globPatterns: ['src/**/*.php'],
));

الأسماء المستعارة لأنواع الملفات

يتضمن Greph مجموعة صغيرة من أنواع الملفات المسماة. ويُوسّع كل اسم مستعار إلى قائمة امتدادات:

الاسم المستعار	الامتدادات
`css`	`css`، `sass`، `scss`
`html`	`htm`، `html`، `phtml`
`js`	`cjs`، `js`، `mjs`
`json`	`json`
`md`	`markdown`، `md`
`php`	`inc`، `php`، `php3`، `php4`، `php5`، `php7`، `php8`، `phpt`، `phtml`
`txt`	`txt`
`ts`	`ts`، `tsx`
`xml`	`xml`
`yaml`	`yaml`، `yml`

توجد القائمة الكاملة في Greph\Walker\FileTypeFilter::TYPE_MAP.

دلالات .gitignore

ينفّذ Greph مطابقة gitignore باستخدام PHP خالص. وتتوافق دلالاته مع git check-ignore:

تُقيّم الأنماط نسبةً إلى المجلد الذي توجد فيه.
تتجاوز ملفات .gitignore المتداخلة القواعد الموروثة من المجلدات الأعلى.
تعيد قاعدة النفي (!pattern) تضمين مسار سبق استبعاده.
يقصر / في نهاية النمط المطابقة على المجلدات.
يربط / في بداية النمط المطابقة بمجلد .gitignore.
يطابق ** أي عدد من مقاطع المسار.

يستخدم .grephignore الصياغة نفسها ويُضاف إلى .gitignore. وهو المكان المناسب لقواعد الاستبعاد الخاصة بالأداة التي لا تريد حفظها في نظام التحكم بالإصدارات.

يوجد التنفيذ في Greph\Walker\GitignoreFilter.

اكتشاف الملفات الثنائية

يفحص المتجوّل أول 512 بايت من كل ملف بحثًا عن بايتات الصفر. وإذا وجدها، يتعامل مع الملف كملف ثنائي ويتخطاه. وهذا يعالج الحالة الشائعة التي يحتوي فيها المستودع على صور أو أرشيفات أو ملفات مبنية داخل مجلد مفهرس.

للبحث في الملفات الثنائية على أي حال، اضبط skipBinaryFiles: false في كائن Options المناسب. لا يتيح CLI حاليًا راية لهذا الغرض؛ استخدم الواجهة.

الروابط الرمزية

لا تُتبع الروابط الرمزية افتراضيًا. اضبط followSymlinks: true (أو مرّر -L / --follow إلى غلاف rg) لتتبّعها. يتعقب المتجوّل المجلدات التي زارها كي لا تؤدي حلقات الروابط الرمزية إلى اجتياز لا نهائي.

الحد الأقصى لحجم الملف

تُتخطى الملفات التي يتجاوز حجمها maxFileSizeBytes (10 MiB افتراضيًا). وهذا يحمي عمليات الفحص من تحميل ملف سجل بحجم 1 GB إلى الذاكرة عن طريق الخطأ. تجاوز الحد في كائن Options عند الحاجة إلى معالجة مدخلات أكبر.

لماذا نستخدم متجوّلًا مخصصًا

يمكن أن يعتمد Greph على glob() أو RecursiveDirectoryIterator، لكن أيًا منهما لا ينفذ دلالات gitignore أو يتعرّف على .grephignore، كما أن التكامل مع تجمع العمال غير سلس في كليهما. وكتابة المتجوّل مرة واحدة ومشاركته بين الأنماط تعني أيضًا تطبيق قواعد التصفية نفسها بدقة في كل نمط، وهذا أمر أساسي لاستراتيجية الاختبار القائمة على المرجع: فلا سبيل للمقارنة مع grep وripgrep وast-grep إلا باجتياز مجموعة الملفات نفسها التي تجتازها تلك الأدوات.