# Reference CLI

Greph obsahuje čtyři spustitelné soubory. Všechny čtyři používají stejný engine; liší se rozhraním, které zpřístupňují.

| Binární soubor | Účel |
|---|---|
| `greph` | Nativní textové vyhledávání, vyhledávání v AST a přepis AST |
| `greph-index` | Předehřátý textový index, index faktů AST a vyhledávání v AST s mezipamětí |
| `rg` | Wrapper kompatibilní se stylem ripgrep |
| `sg` | Wrapper kompatibilní se stylem ast-grep |

Všechny cesty v příkladech používají `./vendor/bin/<binary>`, který funguje s Greph 0.2.3 nainstalovanou jako závislost nebo novější verzí. Pokud pracujete s klonem repozitáře, nahraďte ji za `./bin/<binary>`.

---

## `greph`

Nativní textové vyhledávání, vyhledávání v AST a přepis AST.

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

Pokud cestu vynecháte, prohledá se aktuální adresář.

### Textový režim

Výchozí režim. Vzory jsou regulární výrazy PCRE2, pokud není nastaveno `-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 odpovídá `grep -rn`:

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

### Režim AST

Aktivuje se pomocí `-p`. Vzory se zapisují jako běžné PHP s metaproměnnými `$VAR` a `$$$VARIADIC`. Úplnou gramatiku vzorů najdete v části [Režimy / Vyhledávání v AST](https://greph.inline0.dev/cs/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 přepisu

Aktivuje se kombinací `-p` a `-r`. Šablona náhrady používá stejné metaproměnné jako vyhledávací vzor; zachycené uzly se vkládají podle 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

| Příznak | Význam |
|---|---|
| `-F` | Vyhledávání pevného řetězce (bez regulárních výrazů) |
| `-i` | Porovnávání bez rozlišování velikosti písmen |
| `-w` | Porovnávání celých slov |
| `-v` | Obrátit výběr shod |
| `-c` | Počítat shody v jednotlivých souborech |
| `-l` | Vypsat pouze cesty k souborům se shodami |
| `-L` | Vypsat pouze cesty k souborům bez shod |
| `-h` | V textovém režimu potlačit předpony s názvy souborů |
| `-H` | V textovém režimu vždy vypisovat předpony s názvy souborů |
| `-n` | Zobrazit čísla řádků (výchozí: zapnuto) |
| `-A N` | Zobrazit N řádků za každou shodou |
| `-B N` | Zobrazit N řádků před každou shodou |
| `-C N` | Zobrazit N okolních řádků před každou shodou i za ní |
| `-m N` | Zastavit po N shodách v každém souboru |
| `-j N` | Použít N paralelních pracovníků |
| `-p PATTERN` | Vyhledávací vzor AST |
| `-r TEMPLATE` | Šablona přepisu AST (vyžaduje `-p`) |
| `--glob GLOB` | Zahrnout pouze soubory, jejichž cesty odpovídají GLOB |
| `--type NAME` | Zahrnout alias typu souboru (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Vyloučit alias typu souboru |
| `--lang NAME` | Jazyk AST. Výchozí: `php` |
| `--json` | Vydat výstup JSON |
| `--no-ignore` | Ignorovat pravidla `.gitignore` a `.grephignore` |
| `--hidden` | Zahrnout skryté soubory |
| `--dry-run` | Zobrazit přepisy bez zápisu do souborů |
| `--interactive` | Potvrdit přepis každého souboru |
| `--help` | Zobrazit stručný návod k použití |

---

## `greph-index`

Předehřátý textový index, index faktů AST a vyhledávání v AST s mezipamětí.

```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 předehřáté úložiště trigramů a výskytů identifikátorů. Ve výchozím nastavení se nachází v `.greph-index/` v kořenovém adresáři indexu.

### Sady indexů

Sady indexů převádějí opakované pracovní postupy s více indexy na pojmenovaný 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)' .
```

Výchozí soubor manifestu je `.greph-index-set.json`. Každá položka odkazuje na kořenový adresář, režim a profil životního cyklu. `set build` a `set refresh` pracují s povolenými položkami; `set search` prohledá vybrané položky a odstraní duplicitní překrývající se shody.

### Index faktů 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 faktů AST získává fakta na úrovni uzlů (volání, vytváření instancí, třídy, metody) a ukládá je do úložiště, ve kterém lze vyhledávat. Vyhledávání nejprve provede O(log n) nad klíčem faktu a pak výsledek ověří proti zdrojovému kódu. Ve výchozím nastavení je uložen v `.greph-ast-index/`.

### Mezipaměť 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
```

Mezipaměť AST ukládá analyzované stromy na disk, aby se při vyhledávání nemusel spouštět analyzátor. Ve výchozím nastavení je uložena v `.greph-ast-cache/`.

### Možnosti

Možnosti textového vyhledávání odpovídají sadě příznaků `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Další příznaky:

| Příznak | Význam |
|---|---|
| `--index-dir DIR` | Použít nepředvolený adresář předehřátého indexu. Lze opakovat pro vyhledávání a statistiky ve více indexech. |
| `--lifecycle PROFILE` | Zásada sestavení: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Prahový počet souborů pro příležitostnou aktualizaci |
| `--auto-refresh-max-bytes N` | Prahová velikost v bajtech pro příležitostnou aktualizaci |
| `--manifest FILE` | Načíst manifest sady indexů. Výchozí: `.greph-index-set.json` |
| `--mode MODE` | Omezit operace se sadou na `text`, `ast-index` nebo `ast-cache` |
| `--index NAME` | Omezit operace se sadou na pojmenovanou položku manifestu. Lze opakovat. |
| `--show-index-origin` | Přidat před výstup vyhledávání ve více indexech nebo sadách název odpovídající položky indexu |
| `--trace-plan` | Vydat diagnostiku předehřátého plánovače do `stderr` |
| `--dry-refresh` | V `stats` oznámit, co by předehřáté vyhledávání provedlo, aniž by se cokoli měnilo |
| `--lang NAME` | Jazyk AST pro vyhledávání `ast-index` / `ast-cache`. Výchozí: `php` |
| `-j N`, `--jobs N` | Pracovníci pro prohledávání AST |
| `-l`, `--files-with-matches` | Vypsat pouze cesty k souborům se shodami (režim AST) |
| `--strict-parse` | Při chybách analýzy skončit chybou místo přeskočení |
| `--fallback MODE` | Chování při chybějícím indexu: `fail` (výchozí) nebo `scan` |
| `--help` | Zobrazit stručný návod k použití |

---

## `rg`

Wrapper kompatibilní se stylem ripgrep. Podporuje nejčastěji používané příznaky ripgrep. Ověřené možnosti jsou uvedeny v [matici funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix).

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

### Pří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

| Příznak | Význam |
|---|---|
| `-F`, `--fixed-strings` | Vyhledávání pevného řetězce |
| `-i`, `--ignore-case` | Vyhledávání bez rozlišování velikosti písmen |
| `-w`, `--word-regexp` | Vyhledávání celých slov |
| `-v`, `--invert-match` | Obrátit výběr shod |
| `-c`, `--count` | Počítat řádky se shodami |
| `-l`, `--files-with-matches` | Vypsat soubory se shodami |
| `--files-without-match` | Vypsat soubory bez shod |
| `-I`, `--no-filename` | Potlačit předpony s názvy souborů |
| `-H`, `--with-filename` | Vždy vypisovat předpony s názvy souborů |
| `-n`, `--line-number` | Zobrazit čísla řádků |
| `-A N`, `--after-context N` | Zobrazit N řádků za každou shodou |
| `-B N`, `--before-context N` | Zobrazit N řádků před každou shodou |
| `-C N`, `--context N` | Zobrazit N řádků před každou shodou i za ní |
| `-m N`, `--max-count N` | Zastavit po N shodách v každém souboru |
| `-j N`, `--threads N` | Použít N paralelních pracovníků |
| `-e P`, `--regexp P` | Vyhledávací vzor |
| `-L`, `--follow` | Sledovat symbolické odkazy |
| `--glob GLOB` | Zahrnout pouze soubory, jejichž cesty odpovídají GLOB |
| `--type NAME` | Zahrnout typ souboru |
| `--type-not NAME` | Vyloučit typ souboru |
| `--json` | Vydat události ripgrep ve stylu JSON |
| `--no-ignore` | Ignorovat pravidla `.gitignore` a `.grephignore` |
| `--hidden` | Zahrnout skryté soubory |
| `--files` | Vypsat kandidátní soubory místo vyhledávání |
| `--help` | Zobrazit stručný návod k použití |

---

## `sg`

Wrapper kompatibilní se stylem ast-grep. Podporuje nejčastěji používané příznaky ast-grep. Ověřené možnosti jsou uvedeny v [matici funkcí](https://greph.inline0.dev/cs/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ý příkaz ast-grep. `scan` a `rewrite` jsou pouze aliasy wrapperu, které odpovídají běžnému použití. Funguje i samotné spuštění (`sg --pattern ... .`) jako jednorázové vyhledávání.

### Pří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

| Příznak | Význam |
|---|---|
| `-p`, `--pattern PATTERN` | Vzor AST |
| `-r`, `--rewrite TEMPLATE` | Šablona přepisu |
| `-l`, `--lang NAME` | Jazyk AST. Výchozí: `php` |
| `-j`, `--threads N` | Použít N paralelních pracovníků |
| `-i`, `--interactive` | Potvrdit každý přepis |
| `-U`, `--update-all` | Provést přepisy bez potvrzení |
| `--files-with-matches` | Vypsat pouze cesty k souborům se shodami |
| `--json[=STYLE]` | Vydat výstup JSON. STYLE = `pretty`, `stream` nebo `compact` |
| `--no-ignore [MODE]` | Ignorovat pravidla ignorování repozitáře |
| `--hidden` | Zahrnout skryté soubory |
| `--glob GLOB`, `--globs GLOB` | Zahrnout pouze soubory, jejichž cesty odpovídají GLOB |
| `--type NAME` | Zahrnout typ souboru |
| `--type-not NAME` | Vyloučit typ souboru |
| `--dry-run` | Zobrazit náhled přepisů bez zápisu do souborů |
| `--help` | Zobrazit stručný návod k použití |

---

## Návratové kódy

Greph dodržuje konvence grep / ripgrep:

| Kód | Význam |
|---|---|
| `0` | Byla nalezena alespoň jedna shoda (nebo se v případě přepisů změnil alespoň jeden soubor) |
| `1` | Nebyly nalezeny žádné shody |
| `2` | Chyba použití nebo běhu (chybné argumenty, chybějící index, chyba analýzy v režimu `--strict-parse`) |