# Съвместимост с rg

`vendor/bin/rg` е обвивка за съвместимост в стил ripgrep. Приема най-често използваните флагове на ripgrep, обхожда дървото на файловете като ripgrep и извежда съвпаденията. Потвърденият обхват е възпроизведен чрез пробни изпълнения на оригиналния двоичен файл `rg` и е публикуван в [Разширени / Матрица на функциите](https://greph.inline0.dev/bg/docs/advanced/feature-matrix).

Обвивката е тънък преводач за CLI; самото търсене се извършва от същата машина `Greph\Text\TextSearcher`, която използва `vendor/bin/greph`.

## Кога да го използвате

Използвайте обвивката, когато:

- Имате съществуващ инструмент, агент или скрипт, който вече извиква `rg`.
- Искате директен заместител, който работи в среди, където не можете да инсталирате самия ripgrep (споделен хостинг, защитени контейнери, ограничена PaaS).
- Искате удобството на ripgrep в инфраструктура само с PHP.

Използвайте нативния `vendor/bin/greph`, когато:

- Пишете нов код и не се нуждаете от формата ripgrep CLI.
- Искате достъп до нативни флагове, които обвивката не предоставя (например AST режим).

## Употреба

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

Самостоятелното извикване търси рекурсивно в `.`:

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

`--files` изброява файловете-кандидати вместо да търси:

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

## Изход във формат JSON

`--json` извежда полезните данни със същата структура на събитията, която генерира 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}}}}
```

Времевите стойности в обектите `stats` винаги се извеждат като нула.

Това е схемата, която очакват инструментите надолу по веригата, когато активират структурирания изход на ripgrep. За по-проста структура използвайте `vendor/bin/greph --json`.

## Потвърден обхват

Следните флагове са проверени спрямо самия `rg` в [матрицата на функциите](https://greph.inline0.dev/bg/docs/advanced/feature-matrix). Оригиналният двоичен файл и обвивката генерират еквивалентен изход за всяка проба. Когато флагът има кратък и дълъг запис, пробата използва единия, а обвивката разпознава и двата като една и съща опция.

### Флагове за търсене

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

### Флагове за обхождане

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

### Флагове за изход

- `--json`

### Приемат се без пробна проверка

Обвивката приема и тези флагове, но все още няма пробна проверка за тях в матрицата на функциите:

- `-j N`, `--threads N` (брой работници, вижте [Паралелни работници](https://greph.inline0.dev/bg/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Ограничения

Обвивката `rg` за Greph покрива функциите за търсене и обхождане, които използват повечето инструменти и агенти. В момента не предоставя следните функции на ripgrep:

- Многоредов регулярен израз (`-U`, `--multiline`)
- Замяна (`-r`, `--replace`) в текстов режим (вместо това използвайте `vendor/bin/greph` за AST пренаписване)
- Персонализирани дефиниции на типове (`--type-add`, `--type-clear`)
- Флагове за кодиране (`-E`, `--encoding`)
- Филтриращи скриптове `--pre`
- `--sort`, `--sortr`

Ако ви липсва флаг, подайте сигнал за проблем с пробата, изпълнена спрямо оригиналния `rg`, и очаквания изход. Новите функции се добавят заедно с пробите за сравнение, така че потвърденият обхват непрекъснато се разширява.

## Съответствие на поведението

Обвивката цели съответствие на поведението, а не побайтова идентичност. Резултатът е еквивалентен по редове, но може да се различава в козметични детайли (цветови кодове, съкращаване според ширината на терминала). Пробите за [матрицата на функциите](https://greph.inline0.dev/bg/docs/advanced/feature-matrix) проверяват семантичната еквивалентност, а не побайтови разлики.

За агенти и инструменти, които анализират изхода, полетата, важни за анализатора (път до файла, номер на ред, съдържание, позиция на съвпадението), са побайтно идентични с оригиналния `rg` за всяка проверена проба.