# Справочник CLI

Greph поставляется с четырьмя исполняемыми файлами. Все они используют один движок; различаются лишь предоставляемыми интерфейсами.

| Исполняемый файл | Назначение |
|---|---|
| `greph` | Нативный текстовый поиск, поиск по AST и переписывание AST |
| `greph-index` | Прогретый текстовый индекс, индекс фактов AST и кешированный поиск по AST |
| `rg` | Оболочка совместимости в стиле ripgrep |
| `sg` | Оболочка совместимости в стиле ast-grep |

Во всех примерах используются пути `./vendor/bin/<binary>`, которые работают с Greph 0.2.3 или более поздней версией, установленной как зависимость. Если вы работаете с клоном репозитория, замените путь на `./bin/<binary>`.

---

## `greph`

Нативный текстовый поиск, поиск по AST и переписывание AST.

```bash
greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]
```

Если путь не указан, поиск выполняется в текущем каталоге.

### Текстовый режим

Режим по умолчанию. Шаблоны — это регулярные выражения PCRE2, если не задан `-F`.

```bash
# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src
```

Формат вывода совпадает с `grep -rn`:

```text
src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...
```

### Режим AST

Включается с помощью `-p`. Шаблоны записываются как обычный PHP с метапеременными `$VAR` и `$$$VARIADIC`. Полный синтаксис шаблонов см. в разделе [Режимы / Поиск по AST](https://greph.inline0.dev/ru/docs/modes/ast).

```bash
./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src
```

### Режим переписывания

Включается сочетанием `-p` и `-r`. В шаблоне замены используются те же метапеременные, что и в шаблоне поиска; захваченные узлы вставляются по имени.

```bash
# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

### Параметры

| Флаг | Значение |
|---|---|
| `-F` | Поиск фиксированной строки (без регулярных выражений) |
| `-i` | Поиск без учета регистра |
| `-w` | Поиск целых слов |
| `-v` | Инвертировать совпадения |
| `-c` | Подсчитать совпадения в каждом файле |
| `-l` | Показать только пути к файлам с совпадениями |
| `-L` | Показать только пути к файлам без совпадений |
| `-h` | Не выводить префиксы с именами файлов в текстовом режиме |
| `-H` | Всегда выводить префиксы с именами файлов в текстовом режиме |
| `-n` | Показывать номера строк (по умолчанию: включено) |
| `-A N` | Показывать N строк после каждого совпадения |
| `-B N` | Показывать N строк перед каждым совпадением |
| `-C N` | Показывать N строк контекста до и после каждого совпадения |
| `-m N` | Остановиться после N совпадений в каждом файле |
| `-j N` | Использовать N параллельных исполнителей |
| `-p PATTERN` | Шаблон поиска по AST |
| `-r TEMPLATE` | Шаблон переписывания AST (требуется `-p`) |
| `--glob GLOB` | Включать только файлы, пути которых соответствуют GLOB |
| `--type NAME` | Включить псевдоним типа файла (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Исключить псевдоним типа файла |
| `--lang NAME` | Язык AST. По умолчанию: `php` |
| `--json` | Выводить результат в формате JSON |
| `--no-ignore` | Игнорировать правила `.gitignore` и `.grephignore` |
| `--hidden` | Включать скрытые файлы |
| `--dry-run` | Показывать результаты переписывания без записи в файлы |
| `--interactive` | Подтверждать переписывание каждого файла |
| `--help` | Показывать краткую справку по использованию |

---

## `greph-index`

Прогретый текстовый индекс, индекс фактов AST и кешированный поиск по AST.

```bash
greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]
```

### Текстовый индекс

```bash
# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin
```

Текстовый индекс — это прогретое хранилище триграмм и списков идентификаторов. По умолчанию он находится в `.greph-index/` в корневом каталоге индексации.

### Наборы индексов

Наборы индексов превращают повторяющиеся рабочие процессы с несколькими индексами в именованный манифест:

```bash
./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .
```

Файл манифеста по умолчанию — `.greph-index-set.json`. Каждая запись указывает корневой каталог, режим и профиль жизненного цикла. `set build` и `set refresh` работают с включенными записями; `set search` выполняет поиск по выбранным записям и удаляет дубликаты пересекающихся совпадений.

### Индекс фактов AST

```bash
./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin
```

Индекс фактов AST извлекает факты на уровне узлов (вызовы, инстанцирования, классы, методы) в хранилище с возможностью запросов. Поиск выполняется O(log n) по ключу факта, а затем результат проверяется по исходному коду. По умолчанию хранится в `.greph-ast-index/`.

### Кеш AST

```bash
./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src
```

Кеш AST хранит разобранные деревья на диске, поэтому при поиске парсер не запускается. По умолчанию хранится в `.greph-ast-cache/`.

### Параметры

Параметры текстового поиска соответствуют набору флагов `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Дополнительные флаги:

| Флаг | Значение |
|---|---|
| `--index-dir DIR` | Использовать каталог прогретого индекса вместо каталога по умолчанию. Можно указывать несколько раз для поиска и статистики по нескольким индексам. |
| `--lifecycle PROFILE` | Политика построения: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Порог количества файлов для обновления по возможности |
| `--auto-refresh-max-bytes N` | Порог объема данных в байтах для обновления по возможности |
| `--manifest FILE` | Загрузить манифест набора индексов. По умолчанию: `.greph-index-set.json` |
| `--mode MODE` | Ограничить операции с набором значениями `text`, `ast-index` или `ast-cache` |
| `--index NAME` | Ограничить операции с набором указанной записью манифеста. Можно указывать несколько раз. |
| `--show-index-origin` | Добавлять к выводу прогретого поиска по нескольким индексам или набору имя соответствующей записи индекса |
| `--trace-plan` | Выводить диагностику прогретого планировщика в `stderr` |
| `--dry-refresh` | В режиме `stats` сообщать, что сделал бы прогретый поиск, не изменяя данные |
| `--lang NAME` | Язык AST для поисков `ast-index` / `ast-cache`. По умолчанию: `php` |
| `-j N`, `--jobs N` | Исполнители для сканирования AST |
| `-l`, `--files-with-matches` | Показать только пути к файлам с совпадениями (режим AST) |
| `--strict-parse` | Завершаться при ошибках разбора, а не пропускать файлы |
| `--fallback MODE` | Поведение при отсутствии индекса: `fail` (по умолчанию) или `scan` |
| `--help` | Показывать краткую справку по использованию |

---

## `rg`

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

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

### Примеры

```bash
./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .
```

### Поддерживаемые параметры

| Флаг | Значение |
|---|---|
| `-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` | Показывать N строк после каждого совпадения |
| `-B N`, `--before-context N` | Показывать N строк перед каждым совпадением |
| `-C N`, `--context N` | Показывать N строк до и после каждого совпадения |
| `-m N`, `--max-count N` | Остановиться после N совпадений в каждом файле |
| `-j N`, `--threads N` | Использовать N параллельных исполнителей |
| `-e P`, `--regexp P` | Шаблон поиска |
| `-L`, `--follow` | Следовать по символическим ссылкам |
| `--glob GLOB` | Включать только файлы, пути которых соответствуют GLOB |
| `--type NAME` | Включить тип файла |
| `--type-not NAME` | Исключить тип файла |
| `--json` | Выводить события ripgrep-формата JSON |
| `--no-ignore` | Игнорировать правила `.gitignore` и `.grephignore` |
| `--hidden` | Включать скрытые файлы |
| `--files` | Перечислить файлы-кандидаты вместо поиска |
| `--help` | Показывать краткую справку по использованию |

---

## `sg`

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

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` — каноническая команда ast-grep. `scan` и `rewrite` — псевдонимы только для оболочек, повторяющие распространенный способ использования. Также работает запуск без аргументов (`sg --pattern ... .`) для однократного поиска.

### Примеры

```bash
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php
```

### Поддерживаемые параметры

| Флаг | Значение |
|---|---|
| `-p`, `--pattern PATTERN` | Шаблон AST |
| `-r`, `--rewrite TEMPLATE` | Шаблон переписывания |
| `-l`, `--lang NAME` | Язык AST. По умолчанию: `php` |
| `-j`, `--threads N` | Использовать N параллельных исполнителей |
| `-i`, `--interactive` | Подтверждать каждое переписывание |
| `-U`, `--update-all` | Применять переписывания без подтверждения |
| `--files-with-matches` | Показывать только пути файлов с совпадениями |
| `--json[=STYLE]` | Выводить результат в формате JSON. STYLE = `pretty`, `stream` или `compact` |
| `--no-ignore [MODE]` | Игнорировать правила исключения репозитория |
| `--hidden` | Включать скрытые файлы |
| `--glob GLOB`, `--globs GLOB` | Включать только файлы, пути которых соответствуют GLOB |
| `--type NAME` | Включить тип файла |
| `--type-not NAME` | Исключить тип файла |
| `--dry-run` | Предварительно просмотреть переписывания без записи в файлы |
| `--help` | Показывать краткую справку по использованию |

---

## Коды завершения

Greph следует соглашениям grep / ripgrep:

| Код | Значение |
|---|---|
| `0` | Найдено хотя бы одно совпадение (или при переписывании изменен хотя бы один файл) |
| `1` | Совпадений не найдено |
| `2` | Ошибка использования или выполнения (неверные аргументы, отсутствующий индекс, ошибка разбора в режиме `--strict-parse`) |