# Referenca CLI

Greph vključuje štiri izvršne datoteke. Vse uporabljajo isti pogon; razlikujejo se po vmesniku, ki ga ponujajo.

| Binarna datoteka | Namen |
|---|---|
| `greph` | Izvorno iskanje besedila, iskanje AST in prepisovanje AST |
| `greph-index` | Vnaprej ogret besedilni indeks, indeks dejstev AST in predpomnjeno iskanje AST |
| `rg` | Ovojnica za združljivost v slogu ripgrep |
| `sg` | Ovojnica za združljivost v slogu ast-grep |

Vse poti v primerih uporabljajo `./vendor/bin/<binary>`, ki deluje z Greph 0.2.3 ali novejšim, nameščenim kot odvisnost. Če delate s klonom repozitorija, zamenjajte z `./bin/<binary>`.

---

## `greph`

Izvorno iskanje besedila, iskanje AST in prepisovanje AST.

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

Če pot izpustite, se preišče trenutni imenik.

### Besedilni način

Privzeti način. Vzorci so regularni izrazi PCRE2, razen če je nastavljen `-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
```

Izhodna oblika se ujema z `grep -rn`:

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

### Način AST

Aktivira se z `-p`. Vzorci so zapisani kot običajna PHP z metavariablami `$VAR` in `$$$VARIADIC`. Celotno slovnico vzorcev najdete v [Načini / Iskanje AST](https://greph.inline0.dev/sl/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
```

### Način prepisovanja

Aktivira se s kombinacijo `-p` in `-r`. Predloga za zamenjavo uporablja iste metavariable kot iskalni vzorec; zajeta vozlišča se vstavijo po imenu.

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

| Zastavica | Pomen |
|---|---|
| `-F` | Iskanje nespremenljivega niza (brez regularnih izrazov) |
| `-i` | Iskanje brez razlikovanja med velikimi in malimi črkami |
| `-w` | Iskanje celih besed |
| `-v` | Obrni ujemanje |
| `-c` | Preštej ujemanja v posamezni datoteki |
| `-l` | Izpiši samo poti do datotek z ujemanji |
| `-L` | Izpiši samo poti do datotek brez ujemanj |
| `-h` | V besedilnem načinu skrij predpone imen datotek |
| `-H` | V besedilnem načinu vedno izpiši predpone imen datotek |
| `-n` | Prikaži številke vrstic (privzeto: vklopljeno) |
| `-A N` | Prikaži N vrstic za vsakim ujemanjem |
| `-B N` | Prikaži N vrstic pred vsakim ujemanjem |
| `-C N` | Prikaži N kontekstnih vrstic pred vsakim ujemanjem in za njim |
| `-m N` | Ustavi po N ujemanjih v posamezni datoteki |
| `-j N` | Uporabi N vzporednih delavcev |
| `-p PATTERN` | Iskalni vzorec AST |
| `-r TEMPLATE` | Predloga za prepis AST (zahteva `-p`) |
| `--glob GLOB` | Vključi samo datoteke, katerih poti se ujemajo z GLOB |
| `--type NAME` | Vključi vzdevek vrste datotek (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Izključi vzdevek vrste datotek |
| `--lang NAME` | Jezik AST. Privzeto: `php` |
| `--json` | Izpiši izhod JSON |
| `--no-ignore` | Prezri pravili `.gitignore` in `.grephignore` |
| `--hidden` | Vključi skrite datoteke |
| `--dry-run` | Izpiši prepise, ne da bi zapisali spremembe v datoteke |
| `--interactive` | Potrdi vsak prepis datoteke |
| `--help` | Prikaži kratka navodila za uporabo |

---

## `greph-index`

Vnaprej ogret besedilni indeks, indeks dejstev AST in predpomnjeno iskanje 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...]
```

### Besedilni indeks

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

Besedilni indeks je vnaprej ogreta shramba trigramskih in identifikatorskih objav. Privzeto je shranjen v `.greph-index/` v indeksiranem korenu.

### Nabori indeksov

Nabori indeksov ponavljajoče se poteke dela z več indeksi združijo v imenovani 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)' .
```

Privzeta datoteka manifesta je `.greph-index-set.json`. Vsak vnos kaže na koren, način in profil življenjskega cikla. `set build` in `set refresh` delujeta na omogočenih vnosih; `set search` se izvede v izbranih vnosih in odstrani podvojena prekrivajoča se ujemanja.

### Indeks dejstev 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
```

Indeks dejstev AST izlušči dejstva na ravni vozlišč (klice, instanciacije, razrede, metode) v shrambo, ki jo je mogoče poizvedovati. Iskanja po ključu dejstva so O(log n), nato se preverijo glede na izvorno kodo. Privzeto so shranjena v `.greph-ast-index/`.

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

Predpomnilnik AST shranjuje razčlenjena drevesa na disk, zato iskanja v celoti preskočijo razčlenjevalnik. Privzeto je shranjen v `.greph-ast-cache/`.

### Možnosti

Možnosti iskanja besedila ustrezajo naboru zastavic `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Dodatne zastavice:

| Zastavica | Pomen |
|---|---|
| `--index-dir DIR` | Uporabi drug imenik vnaprej ogretega indeksa. Ponovljivo za iskanje in statistiko z več indeksi. |
| `--lifecycle PROFILE` | Pravilnik gradnje: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Prag datotek za priložnostno osvežitev |
| `--auto-refresh-max-bytes N` | Prag bajtov za priložnostno osvežitev |
| `--manifest FILE` | Naloži manifest nabora indeksov. Privzeto: `.greph-index-set.json` |
| `--mode MODE` | Omeji operacije nad naborom na `text`, `ast-index` ali `ast-cache` |
| `--index NAME` | Omeji operacije nad naborom na imenovani vnos manifesta. Ponovljivo. |
| `--show-index-origin` | Pred izhodom iskanja ali nabora vnaprej ogretih več indeksov dodaj ime ustreznega vnosa indeksa |
| `--trace-plan` | Izpiši diagnostiko vnaprej ogretega načrtovalnika v `stderr` |
| `--dry-refresh` | V `stats` sporoči, kaj bi naredilo vnaprej ogreto iskanje, ne da bi karkoli spremenilo |
| `--lang NAME` | Jezik AST za iskanja `ast-index` / `ast-cache`. Privzeto: `php` |
| `-j N`, `--jobs N` | Delavci za pregledovanje AST |
| `-l`, `--files-with-matches` | Izpiši samo poti do datotek z ujemanji (način AST) |
| `--strict-parse` | Ob napakah pri razčlenjevanju prenehaj, namesto da preskočiš datoteke |
| `--fallback MODE` | Ravnanje ob manjkajočem indeksu: `fail` (privzeto) ali `scan` |
| `--help` | Prikaži kratka navodila za uporabo |

---

## `rg`

Ovojnica za združljivost v slogu ripgrep. Podpira najpogosteje uporabljene zastavice ripgrep. Preverjeni nabor je objavljen v [matriki funkcij](https://greph.inline0.dev/sl/docs/advanced/feature-matrix).

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

### Primeri

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

### Podprte možnosti

| Zastavica | Pomen |
|---|---|
| `-F`, `--fixed-strings` | Iskanje nespremenljivega niza |
| `-i`, `--ignore-case` | Iskanje brez razlikovanja med velikimi in malimi črkami |
| `-w`, `--word-regexp` | Iskanje celih besed |
| `-v`, `--invert-match` | Obrni ujemanja |
| `-c`, `--count` | Preštej vrstice z ujemanji |
| `-l`, `--files-with-matches` | Izpiši datoteke z ujemanji |
| `--files-without-match` | Izpiši datoteke brez ujemanj |
| `-I`, `--no-filename` | Skrij predpone imen datotek |
| `-H`, `--with-filename` | Vedno izpiši predpone imen datotek |
| `-n`, `--line-number` | Prikaži številke vrstic |
| `-A N`, `--after-context N` | Prikaži N vrstic za vsakim ujemanjem |
| `-B N`, `--before-context N` | Prikaži N vrstic pred vsakim ujemanjem |
| `-C N`, `--context N` | Prikaži N vrstic pred vsakim ujemanjem in za njim |
| `-m N`, `--max-count N` | Ustavi po N ujemanjih v posamezni datoteki |
| `-j N`, `--threads N` | Uporabi N vzporednih delavcev |
| `-e P`, `--regexp P` | Iskalni vzorec |
| `-L`, `--follow` | Sledi simbolnim povezavam |
| `--glob GLOB` | Vključi samo datoteke, katerih poti se ujemajo z GLOB |
| `--type NAME` | Vključi vrsto datoteke |
| `--type-not NAME` | Izključi vrsto datoteke |
| `--json` | Izpiši dogodke ripgrep v slogu JSON |
| `--no-ignore` | Prezri pravili `.gitignore` in `.grephignore` |
| `--hidden` | Vključi skrite datoteke |
| `--files` | Izpiši seznam datotek kandidatov, namesto da jih preiščeš |
| `--help` | Prikaži kratka navodila za uporabo |

---

## `sg`

Ovojnica za združljivost v slogu ast-grep. Podpira najpogosteje uporabljene zastavice ast-grep. Preverjeni nabor je objavljen v [matriki funkcij](https://greph.inline0.dev/sl/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 kanonični glagol ast-grep. `scan` in `rewrite` sta vzdevka, namenjena samo ovojnici, ki odražata običajno rabo. Deluje tudi samostojen klic (`sg --pattern ... .`) za enkratno iskanje.

### Primeri

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

### Podprte možnosti

| Zastavica | Pomen |
|---|---|
| `-p`, `--pattern PATTERN` | Vzorec AST |
| `-r`, `--rewrite TEMPLATE` | Predloga za prepisovanje |
| `-l`, `--lang NAME` | Jezik AST. Privzeto: `php` |
| `-j`, `--threads N` | Uporabi N vzporednih delavcev |
| `-i`, `--interactive` | Potrdi vsak prepis |
| `-U`, `--update-all` | Uporabi prepise brez potrditve |
| `--files-with-matches` | Izpiši samo poti do datotek z ujemanji |
| `--json[=STYLE]` | Izpiši izhod JSON. SLOG = `pretty`, `stream` ali `compact` |
| `--no-ignore [MODE]` | Prezri pravila za izključitev v repozitoriju |
| `--hidden` | Vključi skrite datoteke |
| `--glob GLOB`, `--globs GLOB` | Vključi samo datoteke, katerih poti se ujemajo z GLOB |
| `--type NAME` | Vključi vrsto datoteke |
| `--type-not NAME` | Izključi vrsto datoteke |
| `--dry-run` | Predoglej prepise, ne da bi zapisali spremembe v datoteke |
| `--help` | Prikaži kratka navodila za uporabo |

---

## Izhodne kode

Greph sledi konvencijam programov grep / ripgrep:

| Koda | Pomen |
|---|---|
| `0` | Najdeno je bilo vsaj eno ujemanje (ali pa se je pri prepisovanju spremenila vsaj ena datoteka) |
| `1` | Ni bilo najdenih ujemanj |
| `2` | Napaka pri uporabi ali med izvajanjem (neveljavni argumenti, manjkajoči indeks, napaka pri razčlenjevanju v načinu `--strict-parse`) |