# Zgodność z rg

`vendor/bin/rg` to warstwa zgodności w stylu ripgrep. Przyjmuje najczęściej używane flagi ripgrep, przechodzi po drzewie plików tak samo jak ripgrep i emituje pasujące wyniki. Zweryfikowany zakres odtworzono na podstawie uruchomień próbnych wobec nadrzędnego pliku wykonywalnego `rg` i opisano w sekcji [Zaawansowane / macierz funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix).

Ta warstwa opakowująca jest prostym translatorem CLI; właściwe wyszukiwanie wykonuje ten sam silnik `Greph\Text\TextSearcher`, z którego korzysta `vendor/bin/greph`.

## Kiedy używać

Użyj warstwy opakowującej, gdy:

- Masz istniejące narzędzie, agenta lub skrypt, który już wywołuje `rg`.
- Chcesz zamiennika, który działa w środowiskach, w których nie możesz zainstalować samego ripgrep (hosting współdzielony, wzmocnione zabezpieczeniami kontenery, ograniczona platforma PaaS).
- Chcesz korzystać z wygody ripgrep w infrastrukturze obsługującej wyłącznie PHP.

Użyj natywnego `vendor/bin/greph`, gdy:

- Piszesz nowy kod i nie potrzebujesz formatu ripgrep CLI.
- Chcesz mieć dostęp do natywnych flag, których nie udostępnia warstwa opakowująca (na przykład trybu AST).

## Użycie

```bash
rg [options] pattern [path...]
rg --files [options] [path...]
```

Samo wywołanie rekurencyjnie przeszukuje `.`:

```bash
./vendor/bin/rg -F "function"
```

`--files` wyświetla pliki kandydujące zamiast wyszukiwać:

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## Dane wyjściowe JSON

`--json` emituje ładunek w tym samym kształcie zdarzeń, co ripgrep:

```bash
./vendor/bin/rg --json -F "function walk" src/Greph.php
```

```json
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}
```

Czasy w obiektach `stats` są zawsze równe zero.

Taki schemat oczekują narzędzia dalszego przetwarzania po włączeniu strukturalnych danych wyjściowych ripgrep. Aby uzyskać prostszą strukturę, użyj zamiast tego `vendor/bin/greph --json`.

## Zweryfikowany zakres

Poniższe flagi zweryfikowano bezpośrednio względem `rg` w [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix). Nadrzędny plik wykonywalny i warstwa opakowująca generują równoważne dane wyjściowe dla każdej próby. Jeśli flaga ma krótką i długą nazwę, próba używa jednej z nich, a warstwa opakowująca rozpoznaje obie jako tę samą opcję.

### Flagi wyszukiwania

- `-F`, `--fixed-strings`
- `-i`, `--ignore-case`
- `-w`, `--word-regexp`
- `-v`, `--invert-match`
- `-c`, `--count`
- `-l`, `--files-with-matches`
- `--files-without-match`
- `-I`, `--no-filename`
- `-H`, `--with-filename`
- `-n`, `--line-number`
- `-A N`, `--after-context N`
- `-B N`, `--before-context N`
- `-C N`, `--context N`
- `-m N`, `--max-count N`
- `-e P`, `--regexp P`

### Flagi przechodzenia po plikach

- `-L`, `--follow`
- `--glob GLOB`
- `--type NAME`
- `--type-not NAME`
- `--no-ignore`
- `--hidden`
- `--files`
- `--files --hidden`
- `--files --type NAME`

### Flagi wyjściowe

- `--json`

### Akceptowane bez próby

Warstwa opakowująca akceptuje także poniższe flagi, ale nie zostały one jeszcze objęte próbą w macierzy funkcji:

- `-j N`, `--threads N` (liczba procesów roboczych, zob. [Praca równoległa](https://greph.inline0.dev/pl/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Ograniczenia

Warstwa opakowująca `rg` dla Greph obejmuje funkcje wyszukiwania i przechodzenia po plikach używane przez większość narzędzi i agentów. Obecnie nie udostępnia następujących funkcji ripgrep:

- Wyrażenia regularne wielowierszowe (`-U`, `--multiline`)
- Zastępowanie (`-r`, `--replace`) w trybie tekstowym (zamiast tego użyj przepisywania AST `vendor/bin/greph`)
- Niestandardowe definicje typów (`--type-add`, `--type-clear`)
- Flagi kodowania (`-E`, `--encoding`)
- Skrypty filtrujące `--pre`
- `--sort`, `--sortr`

Jeśli brakuje jakiejś flagi, zgłoś problem i dołącz próbę uruchomioną wobec nadrzędnego `rg` oraz oczekiwane dane wyjściowe. Nowe funkcje trafiają do projektu wraz z odpowiadającymi im próbami wzorcowymi, dzięki czemu zweryfikowany zakres stale się powiększa.

## Zgodność zachowania

Warstwa opakowująca dąży do zgodności zachowania, a nie zgodności bajtowej. Dane wyjściowe są równoważne wiersz po wierszu, ale mogą różnić się w szczegółach kosmetycznych (kody kolorów, obcinanie tekstu do szerokości terminala). Próby użyte w [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix) sprawdzają równoważność semantyczną, a nie dokładną zgodność bajtową.

W przypadku agentów i narzędzi analizujących dane wyjściowe pola istotne dla parsera (ścieżka pliku, numer wiersza, treść, pozycja dopasowania) są identyczne bajtowo z nadrzędnym `rg` we wszystkich zweryfikowanych próbach.