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

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

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

Оболочка `rg` для Greph охватывает возможности поиска и обхода, используемые большинством инструментов и агентов. Сейчас в ней недоступны следующие функции ripgrep:

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

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

## Соответствие поведению

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

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