# Referencia CLI

Greph obsahuje štyri spustiteľné súbory. Všetky štyri zdieľajú rovnaký modul; líšia sa tým, aké rozhranie poskytujú.

| Binárny súbor | Účel |
|---|---|
| `greph` | Natívne textové vyhľadávanie, vyhľadávanie AST a prepisovanie AST |
| `greph-index` | Zahriaty textový index, index faktov AST a vyhľadávanie AST s vyrovnávacou pamäťou |
| `rg` | Obal kompatibilný so štýlom ripgrep |
| `sg` | Obal kompatibilný so štýlom ast-grep |

Všetky cesty v príkladoch používajú `./vendor/bin/<binary>`, ktoré funguje s Greph 0.2.3 alebo novším nainštalovaným ako závislosť. Ak pracujete s klonom repozitára, nahraďte ho hodnotou `./bin/<binary>`.

---

## `greph`

Natívne textové vyhľadávanie, vyhľadávanie AST a prepisovanie AST.

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

Ak cestu vynecháte, prehľadá sa aktuálny adresár.

### Textový režim

Predvolený režim. Vzory sú regulárne výrazy PCRE2, pokiaľ nie je nastavené `-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
```

Formát výstupu zodpovedá `grep -rn`:

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

### Režim AST

Aktivuje sa pomocou `-p`. Vzory sa zapisujú ako bežné PHP s metapremennými `$VAR` a `$$$VARIADIC`. Úplnú gramatiku vzorov nájdete v časti [Režimy / Vyhľadávanie AST](https://greph.inline0.dev/sk/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
```

### Režim prepisovania

Aktivuje sa kombináciou `-p` a `-r`. Šablóna náhrady používa rovnaké metapremenné ako vzor vyhľadávania; zachytené uzly sa vkladajú podľa názvu.

```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
```

### Možnosti

| Prepínač | Význam |
|---|---|
| `-F` | Vyhľadávanie pevného reťazca (bez regulárnych výrazov) |
| `-i` | Zhoda bez rozlišovania veľkých a malých písmen |
| `-w` | Zhoda celého slova |
| `-v` | Obrátiť podmienku zhody |
| `-c` | Počítať zhody v jednotlivých súboroch |
| `-l` | Vypísať iba cesty súborov so zhodou |
| `-L` | Vypísať iba cesty súborov bez zhody |
| `-h` | V textovom režime potlačiť predpony s názvami súborov |
| `-H` | V textovom režime vždy vypisovať predpony s názvami súborov |
| `-n` | Zobrazovať čísla riadkov (predvolené: zapnuté) |
| `-A N` | Zobraziť N riadkov za každou zhodou |
| `-B N` | Zobraziť N riadkov pred každou zhodou |
| `-C N` | Zobraziť N kontextových riadkov pred každou zhodou aj za ňou |
| `-m N` | Zastaviť po N zhodách v každom súbore |
| `-j N` | Použiť N paralelných pracovníkov |
| `-p PATTERN` | Vzor vyhľadávania AST |
| `-r TEMPLATE` | Šablóna na prepis AST (vyžaduje `-p`) |
| `--glob GLOB` | Zahrnúť iba súbory, ktorých cesty zodpovedajú GLOB |
| `--type NAME` | Zahrnúť alias typu súboru (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Vylúčiť alias typu súboru |
| `--lang NAME` | Jazyk AST. Predvolený: `php` |
| `--json` | Vytvárať výstup JSON |
| `--no-ignore` | Ignorovať pravidlá `.gitignore` a `.grephignore` |
| `--hidden` | Zahrnúť skryté súbory |
| `--dry-run` | Vypísať prepísané zmeny bez zápisu do súborov |
| `--interactive` | Potvrdiť každý prepísaný súbor |
| `--help` | Zobraziť stručný návod na použitie |

---

## `greph-index`

Zahriaty textový index, index faktov AST a vyhľadávanie AST s vyrovnávacou pamäťou.

```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...]
```

### Textový index

```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
```

Textový index je zahriaté úložisko trigramov a príspevkov identifikátorov. Predvolene sa nachádza v `.greph-index/` v koreňovom adresári indexu.

### Množiny indexov

Množiny indexov premenia opakované pracovné postupy s viacerými indexmi na pomenovaný manifest:

```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)' .
```

Predvolený súbor manifestu je `.greph-index-set.json`. Každá položka odkazuje na koreňový adresár, režim a profil životného cyklu. `set build` a `set refresh` pracujú so zapnutými položkami; `set search` spracuje vybrané položky a odstráni duplicitné prekrývajúce sa zhody.

### Index faktov 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
```

Index faktov AST získava fakty na úrovni uzlov (volania, vytvorenia inštancií, triedy, metódy) a ukladá ich do úložiska, v ktorom možno vyhľadávať. Vyhľadávania sú O(log n) podľa kľúča faktu a následne sa overujú v zdrojovom kóde. Predvolene sa ukladajú do `.greph-ast-index/`.

### Vyrovnávacia pamäť 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
```

Vyrovnávacia pamäť AST ukladá parsované stromy na disk, takže pri vyhľadávaní sa celý parser preskočí. Predvolene sa ukladá do `.greph-ast-cache/`.

### Možnosti

Možnosti textového vyhľadávania zodpovedajú množine prepínačov `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Ďalšie prepínače:

| Prepínač | Význam |
|---|---|
| `--index-dir DIR` | Použiť nepredvolený adresár zahriateho indexu. Možno opakovať pri vyhľadávaní a štatistikách vo viacerých indexoch. |
| `--lifecycle PROFILE` | Politika zostavovania: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Prahová hodnota počtu súborov na príležitostné obnovenie |
| `--auto-refresh-max-bytes N` | Prahová hodnota počtu bajtov na príležitostné obnovenie |
| `--manifest FILE` | Načítať manifest množiny indexov. Predvolený: `.greph-index-set.json` |
| `--mode MODE` | Obmedziť operácie s množinami na `text`, `ast-index` alebo `ast-cache` |
| `--index NAME` | Obmedziť operácie s množinami na pomenovanú položku manifestu. Možno opakovať. |
| `--show-index-origin` | Predponou výstupu pri zahriatom vyhľadávaní vo viacerých indexoch alebo množinách označiť názov príslušnej položky indexu |
| `--trace-plan` | Odosielať diagnostiku zahriateho plánovača do `stderr` |
| `--dry-refresh` | V `stats` oznámiť, čo by zahriaté vyhľadávanie vykonalo, bez zmeny čohokoľvek |
| `--lang NAME` | Jazyk AST pre vyhľadávanie `ast-index` / `ast-cache`. Predvolený: `php` |
| `-j N`, `--jobs N` | Pracovníci pre prehľadávanie AST |
| `-l`, `--files-with-matches` | Vypísať iba cesty súborov so zhodou (režim AST) |
| `--strict-parse` | Pri chybách parsovania skončiť namiesto preskočenia |
| `--fallback MODE` | Správanie pri chýbajúcom indexe: `fail` (predvolené) alebo `scan` |
| `--help` | Zobraziť stručný návod na použitie |

---

## `rg`

Obal kompatibilný so štýlom ripgrep. Podporuje najčastejšie používané prepínače ripgrep. Overený rozsah je uvedený v [matica funkcií](https://greph.inline0.dev/sk/docs/advanced/feature-matrix).

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

### Príklady

```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" .
```

### Podporované možnosti

| Prepínač | Význam |
|---|---|
| `-F`, `--fixed-strings` | Vyhľadávanie pevného reťazca |
| `-i`, `--ignore-case` | Vyhľadávanie bez rozlišovania veľkých a malých písmen |
| `-w`, `--word-regexp` | Vyhľadávanie celého slova |
| `-v`, `--invert-match` | Obrátiť podmienku zhody |
| `-c`, `--count` | Počítať riadky so zhodou |
| `-l`, `--files-with-matches` | Vypísať súbory so zhodou |
| `--files-without-match` | Vypísať súbory bez zhody |
| `-I`, `--no-filename` | Potlačiť predpony s názvami súborov |
| `-H`, `--with-filename` | Vždy vypisovať predpony s názvami súborov |
| `-n`, `--line-number` | Zobrazovať čísla riadkov |
| `-A N`, `--after-context N` | Zobraziť N riadkov za každou zhodou |
| `-B N`, `--before-context N` | Zobraziť N riadkov pred každou zhodou |
| `-C N`, `--context N` | Zobraziť N riadkov pred každou zhodou aj za ňou |
| `-m N`, `--max-count N` | Zastaviť po N zhodách v každom súbore |
| `-j N`, `--threads N` | Použiť N paralelných pracovníkov |
| `-e P`, `--regexp P` | Vzor vyhľadávania |
| `-L`, `--follow` | Nasledovať symbolické odkazy |
| `--glob GLOB` | Zahrnúť iba súbory, ktorých cesty zodpovedajú GLOB |
| `--type NAME` | Zahrnúť typ súboru |
| `--type-not NAME` | Vylúčiť typ súboru |
| `--json` | Vytvárať udalosti ripgrep v štýle JSON |
| `--no-ignore` | Ignorovať pravidlá `.gitignore` a `.grephignore` |
| `--hidden` | Zahrnúť skryté súbory |
| `--files` | Vypísať kandidátne súbory namiesto vyhľadávania |
| `--help` | Zobraziť stručný návod na použitie |

---

## `sg`

Obal kompatibilný so štýlom ast-grep. Podporuje najčastejšie používané prepínače ast-grep. Overený rozsah je uvedený v [matica funkcií](https://greph.inline0.dev/sk/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` je kanonické sloveso ast-grep. `scan` a `rewrite` sú aliasy dostupné iba v obaloch, ktoré kopírujú bežné používanie. Funguje aj samotné zavolanie (`sg --pattern ... .`) ako jednorazové vyhľadávanie.

### Príklady

```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
```

### Podporované možnosti

| Prepínač | Význam |
|---|---|
| `-p`, `--pattern PATTERN` | Vzor AST |
| `-r`, `--rewrite TEMPLATE` | Šablóna na prepisovanie |
| `-l`, `--lang NAME` | Jazyk AST. Predvolený: `php` |
| `-j`, `--threads N` | Použiť N paralelných pracovníkov |
| `-i`, `--interactive` | Potvrdiť každý prepis |
| `-U`, `--update-all` | Použiť prepisy bez potvrdenia |
| `--files-with-matches` | Vypísať iba cesty súborov so zhodami |
| `--json[=STYLE]` | Vytvárať výstup JSON. ŠTÝL = `pretty`, `stream` alebo `compact` |
| `--no-ignore [MODE]` | Ignorovať pravidlá na ignorovanie súborov v repozitári |
| `--hidden` | Zahrnúť skryté súbory |
| `--glob GLOB`, `--globs GLOB` | Zahrnúť iba súbory, ktorých cesty zodpovedajú GLOB |
| `--type NAME` | Zahrnúť typ súboru |
| `--type-not NAME` | Vylúčiť typ súboru |
| `--dry-run` | Zobraziť náhľad prepisov bez zápisu do súborov |
| `--help` | Zobraziť stručný návod na použitie |

---

## Návratové kódy

Greph dodržiava konvencie grep / ripgrep:

| Kód | Význam |
|---|---|
| `0` | Našla sa aspoň jedna zhoda (alebo sa v prípade prepisovania zmenil aspoň jeden súbor) |
| `1` | Nenašli sa žiadne zhody |
| `2` | Chyba pri používaní alebo zlyhanie za behu (nesprávne argumenty, chýbajúci index, chyba parsovania v režime `--strict-parse`) |