# Sprehajalnik datotek

Vsak način Greph (besedilo, AST, prepisovanje, indeksirano besedilo, indeksirani AST, predpomnjeni AST, ovojnik `rg`, ovojnik `sg`) se začne s pregledom drevesa datotek in ustvarjanjem `Greph\Walker\FileList`. Sprehajalnik je skupen, zato povsod veljajo iste zastavice in vedenje.

## Privzeto delovanje

S privzetimi nastavitvami sprehajalnik:

- Rekurzivno pregleda vse imenike pod zahtevanimi potmi.
- Na vseh ravneh upošteva pravila `.gitignore` in `.grephignore`, vključno z gnezdenimi preglasitvami in izjemami.
- Preskoči imenik `.git`.
- Preskoči skrite datoteke in imenike (vse, kar se začne z `.`).
- Preskoči binarne datoteke (zazna jih po ničelnih bajtih v prvih 512 bajtih datoteke).
- Preskoči datoteke, večje od 10 MiB.
- Ne sledi simbolnim povezavam.

## Zastavice za preglasitev

| Zastavica | Učinek |
|---|---|
| `--no-ignore` | Ne upošteva več `.gitignore` in `.grephignore` |
| `--hidden` | Vključi skrite datoteke in imenike |
| `--type NAME` | Vključi samo datoteke, ki ustrezajo imenovanemu vzdevku vrste |
| `--type-not NAME` | Izključi datoteke, ki ustrezajo imenovanemu vzdevku vrste |
| `--glob GLOB` | Vključi samo datoteke, katerih poti ustrezajo vzorcu GLOB. Zastavico je mogoče ponoviti. |

Za programsko uporabo so iste možnosti na voljo prek `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'],
));
```

## Vzdevki vrst datotek

Greph vključuje majhen nabor imenovanih vrst datotek. Vsak vzdevek se razširi v seznam končnic:

| Vzdevek | Končnice |
|---|---|
| `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` |

Celoten seznam je v `Greph\Walker\FileTypeFilter::TYPE_MAP`.

## Semantika .gitignore

Greph izvaja ujemanje po pravilih gitignore v čistem PHP. Semantika je usklajena s `git check-ignore`:

- Vzorci se vrednotijo glede na imenik, v katerem so zapisani.
- Gnezdene datoteke `.gitignore` preglasijo pravila nadrejenih imenikov.
- Negacija (`!pattern`) znova vključi prej izključeno pot.
- Končni `/` omeji vzorec na imenike.
- Začetni `/` zasidra vzorec na imenik datoteke `.gitignore`.
- `**` se ujema s poljubnim številom segmentov poti.

`.grephignore` uporablja isto sintakso in je nadgrajen na `.gitignore`. To je pravo mesto za izključitve, specifične za orodje, ki jih ne želite vključiti v nadzor različic.

Implementacija je v `Greph\Walker\GitignoreFilter`.

## Zaznavanje binarnih datotek

Sprehajalnik preveri prvih 512 bajtov vsake datoteke za ničelne bajte. Če jih najde, datoteko obravnava kot binarno in jo preskoči. Tako zazna pogost primer, ko so v imeniku, vključenem v indeksiranje, slikovne, arhivske ali prevedene datoteke.

Če želite vseeno iskati po binarnih datotekah, nastavite `skipBinaryFiles: false` na ustreznem objektu `Options`. CLI trenutno ne ponuja zastavice za to; uporabite fasado.

## Simbolne povezave

Sprehajalnik privzeto ne sledi simbolnim povezavam. Če jim želite slediti, nastavite `followSymlinks: true` (ali posredujte `-L` / `--follow` ovoju `rg`). Sprehajalnik beleži že obiskane imenike, zato zanke simbolnih povezav ne povzročijo neskončne rekurzije.

## Največja velikost datoteke

Datoteke, večje od `maxFileSizeBytes` (privzeto 10 MiB), so preskočene. Tako pregled ne naloži po pomoti 1 GB velike dnevniške datoteke v pomnilnik. Omejitev lahko preglasite v objektu `Options`, kadar morate obdelati večje vhode.

## Zakaj lastni sprehajalnik

Greph bi se lahko zanašal na `glob()` ali `RecursiveDirectoryIterator`, vendar nobeden ne izvaja semantike gitignore, nobeden ne razume `.grephignore` in nobeden se ne poveže gladko s skupino delavcev. Enkratna izdelava sprehajalnika in njegova souporaba med načini pomenita tudi, da vsak način uporablja povsem enaka pravila filtriranja, kar je ključno za strategijo testiranja na podlagi referenčnih rezultatov: primerjava z `grep`, `ripgrep` in `ast-grep` je mogoča samo, če pregledamo isti nabor datotek kot ta orodja.