# Сумісність із rg

`vendor/bin/rg` — обгортка сумісності у стилі ripgrep. Вона приймає найуживаніші прапорці ripgrep, обходить дерево файлів так само, як ripgrep, і виводить знайдені збіги. Перевірений набір можливостей відтворено за результатами пробних запусків із вихідним бінарним файлом `rg` і наведено в [Додатково / Матриця можливостей](https://greph.inline0.dev/uk/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/uk/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/uk/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Обмеження

Обгортка `rg` для Greph охоплює можливості пошуку й обходу, які використовує більшість інструментів та агентів. Наразі вона не надає доступу до таких можливостей ripgrep:

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

Якщо бракує потрібного прапорця, створіть запит на виправлення та додайте пробу, яку ви виконали з вихідним `rg`, і очікуваний вивід. Нові можливості додаються разом із перевірочними пробами, тож перевірений набір постійно розширюється.

## Відповідність поведінки

Обгортка прагне відповідності поведінки, а не побітової відповідності. Вивід еквівалентний на рівні рядків, але може відрізнятися косметичними деталями (кольорові коди, обрізання за шириною термінала). Проби для [матриці можливостей](https://greph.inline0.dev/uk/docs/advanced/feature-matrix) перевіряють семантичну еквівалентність, а не побітово точні відмінності.

Для агентів та інструментів, які розбирають вивід, поля, важливі для аналізатора (шлях до файлу, номер рядка, вміст, позиція збігу), побітово ідентичні вихідному `rg` для кожної перевіреної проби.