# Довідник 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/uk/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/uk/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/uk/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`) |