Към съдържанието

Обхождач на файлове

Преглед като 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 е възможно само ако се обхожда същият набор от файлове като при тези инструменти.