# Kompatibilita s rg

`vendor/bin/rg` je wrapper kompatibilní se stylem ripgrep. Přijímá nejčastěji používané příznaky ripgrep, prochází strom souborů stejně jako ripgrep a vypisuje odpovídající výsledky. Ověřené možnosti vycházejí z testovacích běhů s upstreamovým binárním souborem `rg` a jsou uvedeny v [Rozšířené funkce / Matice funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix).

Wrapper je tenká překladová vrstva CLI; samotné vyhledávání zajišťuje stejný engine `Greph\Text\TextSearcher`, který používá `vendor/bin/greph`.

## Kdy jej použít

Wrapper použijte, když:

- Máte existující nástroj, agenta nebo skript, který už spouští `rg`.
- Chcete přímou náhradu, která funguje v prostředích, kde nelze nainstalovat samotný ripgrep (sdílený hosting, zabezpečené kontejnery, omezené PaaS).
- Chcete pohodlí ripgrep na infrastruktuře, kde je k dispozici pouze PHP.

Nativní `vendor/bin/greph` použijte, když:

- Píšete nový kód a nepotřebujete rozhraní ripgrep CLI.
- Chcete používat nativní příznaky, které wrapper nezpřístupňuje (například režim AST).

## Použití

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

Samotné spuštění rekurzivně prohledá `.`:

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

`--files` vypíše kandidátní soubory místo vyhledávání:

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

## Výstup JSON

`--json` vydává stejná data ve tvaru událostí jako 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}}}}
```

Časy v objektech `stats` se vždy uvádějí jako nula.

Toto je schéma, které očekávají navazující nástroje při zapnutí strukturovaného výstupu ripgrep. Pokud chcete jednodušší formát, použijte místo toho `vendor/bin/greph --json`.

## Ověřené možnosti

Následující příznaky jsou ověřeny přímo proti `rg` v [matici funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix). Upstreamový binární soubor i wrapper vytvářejí při každém testu rovnocenný výstup. Má-li příznak krátký i dlouhý zápis, test používá jeden z nich a wrapper oba zpracuje jako tutéž volbu.

### Příznaky vyhledávání

- `-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`

### Příznaky procházení

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

### Příznaky výstupu

- `--json`

### Přijímané bez testu

Wrapper přijímá také následující příznaky, na které se zatím nevztahuje žádný test matice funkcí:

- `-j N`, `--threads N` (počet pracovníků, viz [Paralelní pracovníci](https://greph.inline0.dev/cs/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Omezení

Wrapper `rg` pro Greph pokrývá možnosti vyhledávání a procházení, které využívá většina nástrojů a agentů. V současnosti nezpřístupňuje tyto funkce ripgrep:

- Víceřádkový regulární výraz (`-U`, `--multiline`)
- Náhrada (`-r`, `--replace`) v textovém režimu (místo toho použijte přepis AST `vendor/bin/greph`)
- Vlastní definice typů (`--type-add`, `--type-clear`)
- Příznaky kódování (`-E`, `--encoding`)
- Filtrační skripty `--pre`
- `--sort`, `--sortr`

Pokud narazíte na chybějící příznak, založte hlášení a přiložte test provedený proti upstreamovému `rg` i očekávaný výstup. Nové funkce se přidávají spolu s odpovídajícími referenčními testy, takže se ověřené možnosti postupně rozšiřují.

## Shoda chování

Cílem wrapperu je shoda chování, nikoli shoda po bajtech. Výstup odpovídá po řádcích, ale může se lišit v kosmetických detailech (barevné kódy, zkrácení podle šířky terminálu). Testy použité v [matici funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix) ověřují sémantickou shodu, nikoli přesnou shodu po bajtech.

U agentů a nástrojů, které výstup zpracovávají, jsou pole důležitá pro parser (cesta k souboru, číslo řádku, obsah, pozice shody) pro každý ověřený test po bajtech totožná s upstreamovým `rg`.