Procházení souborů

Zobrazit jako Markdown Upravit na GitHub Dokumentace na d105217

Každý režim Greph (text, AST, přepisování, indexovaný text, indexované AST, AST z cache, obal rg, obal sg) začíná procházením stromu souborů a vytvořením Greph\Walker\FileList. Procházeč je sdílený, takže se všude uplatňují stejné příznaky a stejné chování.

Výchozí chování

Ve výchozím nastavení procházeč:

Rekurzivně prochází všechny adresáře pod zadanými cestami.
Na každé úrovni respektuje pravidla .gitignore a .grephignore, včetně vnořených přepsání a negací.
Přeskakuje adresář .git.
Přeskakuje skryté soubory a adresáře (všechny začínající na .).
Přeskakuje binární soubory (určené podle nulových bajtů v prvních 512 bajtech souboru).
Přeskakuje soubory větší než 10 MiB.
Nenásleduje symbolické odkazy.

Příznaky pro přepsání chování

Příznak	Účinek
`--no-ignore`	Přestane respektovat `.gitignore` a `.grephignore`
`--hidden`	Zahrne skryté soubory a adresáře
`--type NAME`	Zahrne pouze soubory odpovídající pojmenovanému aliasu typu
`--type-not NAME`	Vyloučí soubory odpovídající pojmenovanému aliasu typu
`--glob GLOB`	Zahrne pouze soubory, jejichž cesty odpovídají GLOB. Lze opakovat.

Stejné možnosti jsou dostupné pro programové použití prostřednictvím 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'],
));

Aliasy typů souborů

Greph obsahuje malou sadu pojmenovaných typů souborů. Každý alias odpovídá seznamu přípon:

Alias	Přípony
`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`

Úplný seznam je v Greph\Walker\FileTypeFilter::TYPE_MAP.

Sémantika .gitignore

Greph implementuje porovnávání gitignore v čistém PHP. Sémantika odpovídá git check-ignore:

Vzory se vyhodnocují relativně k adresáři, ve kterém jsou umístěny.
Vnořené soubory .gitignore přepisují pravidla nadřazených adresářů.
Negace (!pattern) znovu zahrne dříve vyloučenou cestu.
Závěrečné / omezuje vzor na adresáře.
Počáteční / ukotví vzor k adresáři souboru .gitignore.
** odpovídá libovolnému počtu částí cesty.

.grephignore používá stejnou syntaxi a vrství se nad .gitignore. Slouží k výjimkám specifickým pro nástroje, které nechcete zahrnout do správy verzí.

Implementace je v Greph\Walker\GitignoreFilter.

Detekce binárních souborů

Procházeč kontroluje prvních 512 bajtů každého souboru, zda neobsahují nulové bajty. Pokud nějaké najde, považuje soubor za binární a přeskočí ho. Tím zachytí běžný případ, kdy repozitář obsahuje v indexovaném adresáři obrázky, archivy nebo zkompilované artefakty.

Chcete-li přesto prohledávat binární soubory, nastavte skipBinaryFiles: false v příslušném objektu Options. CLI v současnosti příznak pro tuto možnost nenabízí; použijte fasádu.

Symbolické odkazy

Symbolické odkazy se ve výchozím nastavení nenásledují. Chcete-li je následovat, nastavte followSymlinks: true (nebo předejte -L / --follow obalu rg). Procházeč sleduje navštívené adresáře, aby cykly symbolických odkazů nezpůsobily nekonečnou rekurzi.

Maximální velikost souboru

Soubory větší než maxFileSizeBytes (výchozí hodnota je 10 MiB) se přeskakují. Tím se zabrání nechtěnému načtení 1 GB souboru protokolů do paměti během skenování. Pokud potřebujete zpracovávat větší vstupy, upravte limit v objektu Options.

Proč vlastní procházeč

Greph by mohlo spoléhat na glob() nebo RecursiveDirectoryIterator, ale ani jedno neimplementuje sémantiku gitignore, nerozumí .grephignore a ani jedno se čistě neintegruje s fondem pracovních procesů. Když se procházeč napíše jednou a sdílí mezi režimy, každý režim uplatňuje přesně stejná pravidla filtrování. To je zásadní pro strategii testování řízenou oracle: porovnávat s grep, ripgrep a ast-grep lze pouze při procházení stejné sady souborů, jakou procházejí tyto nástroje.