# Справочник за 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/bg/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/bg/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/bg/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`) |