# CLI žinynas

Greph pateikia keturis vykdomuosius failus. Visi keturi naudoja tą patį variklį; skiriasi tik jų teikiama sąsaja.

| Dvejetainis failas | Paskirtis |
|---|---|
| `greph` | Vietinė tekstinė paieška, AST paieška ir AST perrašymas |
| `greph-index` | Įšildytas tekstinis indeksas, AST faktų indeksas ir spartinančioji AST paieška |
| `rg` | ripgrep stiliaus suderinamumo apvalkalas |
| `sg` | ast-grep stiliaus suderinamumo apvalkalas |

Pavyzdžiuose naudojami keliai prasideda nuo `./vendor/bin/<binary>`; tai veikia, jei Greph 0.2.3 jau įdiegta kaip priklausomybė. Jei dirbate su saugyklos klonu, pakeiskite į `./bin/<binary>`.

---

## `greph`

Vietinė tekstinė paieška, AST paieška ir AST perrašymas.

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

Jei kelias nenurodytas, ieškoma dabartiniame kataloge.

### Teksto režimas

Numatytasis režimas. Šablonai yra PCRE2 regex išraiškos, nebent nustatyta `-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
```

Išvesties formatas atitinka `grep -rn`:

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

### AST režimas

Suaktyvinama naudojant `-p`. Šablonai rašomi kaip įprastas PHP, naudojant `$VAR` ir `$$$VARIADIC` metakintamuosius. Visą šablonų gramatiką rasite skiltyje [AST režimai / AST paieška](https://greph.inline0.dev/lt/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
```

### Perrašymo režimas

Suaktyvinama kartu naudojant `-p` ir `-r`. Pakeitimo šablone naudojami tie patys metakintamieji kaip ir paieškos šablone; užfiksuoti mazgai įterpiami pagal pavadinimą.

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

### Parinktys

| Vėliavėlė | Reikšmė |
|---|---|
| `-F` | Paieška pagal fiksuotą eilutę (be regex) |
| `-i` | Paieška nepaisant raidžių registro |
| `-w` | Paieška pagal visą žodį |
| `-v` | Apversti atitikimą |
| `-c` | Suskaičiuoti atitikmenis kiekviename faile |
| `-l` | Pateikti tik atitinkančių failų kelius |
| `-L` | Pateikti tik neatitinkančių failų kelius |
| `-h` | Teksto režimu nerodyti failų pavadinimų prefiksų |
| `-H` | Teksto režimu visada rodyti failų pavadinimų prefiksus |
| `-n` | Rodyti eilučių numerius (numatyta: įjungta) |
| `-A N` | Rodyti N eilučių po kiekvieno atitikmens |
| `-B N` | Rodyti N eilučių prieš kiekvieną atitikmenį |
| `-C N` | Rodyti N konteksto eilučių prieš kiekvieną atitikmenį ir po jo |
| `-m N` | Sustoti radus N atitikmenų faile |
| `-j N` | Naudoti N lygiagrečių vykdytojų |
| `-p PATTERN` | AST paieškos šablonas |
| `-r TEMPLATE` | AST perrašymo šablonas (reikia `-p`) |
| `--glob GLOB` | Įtraukti tik failus, kurių keliai atitinka GLOB |
| `--type NAME` | Įtraukti failo tipo slapyvardį (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Neįtraukti failo tipo slapyvardžio |
| `--lang NAME` | AST kalba. Numatytoji: `php` |
| `--json` | Generuoti JSON išvestį |
| `--no-ignore` | Nepaisyti `.gitignore` ir `.grephignore` taisyklių |
| `--hidden` | Įtraukti paslėptus failus |
| `--dry-run` | Rodyti perrašymus failų nekeičiant |
| `--interactive` | Patvirtinti kiekvieną perrašytą failą |
| `--help` | Rodyti trumpąją naudojimo instrukciją |

---

## `greph-index`

Įšildytas tekstinis indeksas, AST faktų indeksas ir spartinančioji AST paieška.

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

### Teksto indeksas

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

Teksto indeksas – tai įšildyta trigramų ir identifikatorių įrašų saugykla. Pagal numatytuosius nustatymus ji saugoma indeksuojamo šakninio katalogo vietoje `.greph-index/`.

### Indeksų rinkiniai

Indeksų rinkiniai leidžia pasikartojančias kelių indeksų darbo sekas aprašyti įvardytu manifeste:

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

Numatytasis manifesto failas yra `.greph-index-set.json`. Kiekvienas įrašas nurodo šakninį katalogą, režimą ir gyvavimo ciklo profilį. `set build` ir `set refresh` veikia su įjungtais įrašais; `set search` vykdo paiešką pasirinktuose įrašuose ir pašalina besidubliuojančius atitikmenis.

### AST faktų indeksas

```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 faktų indeksas išskiria mazgų lygmens faktus (iškvietimus, egzempliorių kūrimą, klases, metodus) į užklausoms pritaikytą saugyklą. Pirmiausia pagal faktų raktą atliekama O(log n) paieška, o tada rezultatai patikrinami pagal šaltinį. Pagal numatytuosius nustatymus saugoma adresu `.greph-ast-index/`.

### AST talpykla

```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 talpykloje medyje saugomi išanalizuoti failai, todėl atliekant paiešką analizatoriaus nebereikia. Pagal numatytuosius nustatymus saugoma adresu `.greph-ast-cache/`.

### Parinktys

Tekstinės paieškos parinktys atitinka `greph` vėliavėlių rinkinį (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Papildomos vėliavėlės:

| Vėliavėlė | Reikšmė |
|---|---|
| `--index-dir DIR` | Naudoti ne numatytąjį įšildyto indekso katalogą. Galima kartoti atliekant kelių indeksų paiešką ir gaunant statistiką. |
| `--lifecycle PROFILE` | Kūrimo politika: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Proginio atnaujinimo failų slenkstis |
| `--auto-refresh-max-bytes N` | Proginio atnaujinimo baitų slenkstis |
| `--manifest FILE` | Įkelti indeksų rinkinio manifestą. Numatytoji reikšmė: `.greph-index-set.json` |
| `--mode MODE` | Apriboti rinkinio operacijas iki `text`, `ast-index` arba `ast-cache` |
| `--index NAME` | Apriboti rinkinio operacijas iki įvardyto manifesto įrašo. Galima kartoti. |
| `--show-index-origin` | Įšildytos kelių indeksų arba rinkinio išvesties pradžioje pateikti atitinkamo indekso įrašo pavadinimą |
| `--trace-plan` | Pateikti įšildyto planuoklio diagnostiką į `stderr` |
| `--dry-refresh` | `stats` režimu pranešti, ką darytų įšildyta paieška, nieko nekeičiant |
| `--lang NAME` | AST kalba `ast-index` / `ast-cache` paieškoms. Numatytoji: `php` |
| `-j N`, `--jobs N` | AST paieškų vykdytojai |
| `-l`, `--files-with-matches` | Pateikti tik atitinkančių failų kelius (AST režimu) |
| `--strict-parse` | Nutrūkti įvykus analizės klaidoms, o ne jas praleisti |
| `--fallback MODE` | Elgsena, kai nėra indekso: `fail` (numatytoji) arba `scan` |
| `--help` | Rodyti trumpąją naudojimo instrukciją |

---

## `rg`

ripgrep stiliaus suderinamumo apvalkalas. Palaiko dažniausiai naudojamas ripgrep vėliavėles. Patikrintas funkcijų rinkinys paskelbtas [funkcijų matricoje](https://greph.inline0.dev/lt/docs/advanced/feature-matrix).

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

### Pavyzdžiai

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

### Palaikomos parinktys

| Vėliavėlė | Reikšmė |
|---|---|
| `-F`, `--fixed-strings` | Paieška pagal fiksuotą eilutę |
| `-i`, `--ignore-case` | Paieška nepaisant raidžių registro |
| `-w`, `--word-regexp` | Paieška pagal visą žodį |
| `-v`, `--invert-match` | Apversti atitikmenis |
| `-c`, `--count` | Suskaičiuoti atitinkančias eilutes |
| `-l`, `--files-with-matches` | Pateikti atitinkančius failus |
| `--files-without-match` | Pateikti neatitinkančius failus |
| `-I`, `--no-filename` | Nerodyti failų pavadinimų prefiksų |
| `-H`, `--with-filename` | Visada rodyti failų pavadinimų prefiksus |
| `-n`, `--line-number` | Rodyti eilučių numerius |
| `-A N`, `--after-context N` | Rodyti N eilučių po kiekvieno atitikmens |
| `-B N`, `--before-context N` | Rodyti N eilučių prieš kiekvieną atitikmenį |
| `-C N`, `--context N` | Rodyti N eilučių prieš kiekvieną atitikmenį ir po jo |
| `-m N`, `--max-count N` | Sustoti radus N atitikmenų faile |
| `-j N`, `--threads N` | Naudoti N lygiagrečių vykdytojų |
| `-e P`, `--regexp P` | Paieškos šablonas |
| `-L`, `--follow` | Vykdyti simbolines nuorodas |
| `--glob GLOB` | Įtraukti tik failus, kurių keliai atitinka GLOB |
| `--type NAME` | Įtraukti failo tipą |
| `--type-not NAME` | Neįtraukti failo tipo |
| `--json` | Generuoti ripgrep stiliaus JSON įvykius |
| `--no-ignore` | Nepaisyti `.gitignore` ir `.grephignore` taisyklių |
| `--hidden` | Įtraukti paslėptus failus |
| `--files` | Pateikti galimus failus, o ne atlikti paiešką |
| `--help` | Rodyti trumpąją naudojimo instrukciją |

---

## `sg`

ast-grep stiliaus suderinamumo apvalkalas. Palaiko dažniausiai naudojamas ast-grep vėliavėles. Patikrintas funkcijų rinkinys paskelbtas [funkcijų matricoje](https://greph.inline0.dev/lt/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` yra pagrindinis ast-grep veiksmažodis. `scan` ir `rewrite` yra tik apvalkalo slapyvardžiai, atkartojantys įprastą naudojimą. Galima vykdyti ir be argumentų (`sg --pattern ... .`), jei norite atlikti vienkartinę paiešką.

### Pavyzdžiai

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

### Palaikomos parinktys

| Vėliavėlė | Reikšmė |
|---|---|
| `-p`, `--pattern PATTERN` | AST šablonas |
| `-r`, `--rewrite TEMPLATE` | Perrašymo šablonas |
| `-l`, `--lang NAME` | AST kalba. Numatytoji: `php` |
| `-j`, `--threads N` | Naudoti N lygiagrečių vykdytojų |
| `-i`, `--interactive` | Patvirtinti kiekvieną perrašymą |
| `-U`, `--update-all` | Taikyti perrašymus be patvirtinimo |
| `--files-with-matches` | Pateikti tik failų su atitikmenimis kelius |
| `--json[=STYLE]` | Generuoti JSON išvestį. STYLE = `pretty`, `stream` arba `compact` |
| `--no-ignore [MODE]` | Nepaisyti saugyklos ignoravimo taisyklių |
| `--hidden` | Įtraukti paslėptus failus |
| `--glob GLOB`, `--globs GLOB` | Įtraukti tik failus, kurių keliai atitinka GLOB |
| `--type NAME` | Įtraukti failo tipą |
| `--type-not NAME` | Neįtraukti failo tipo |
| `--dry-run` | Peržiūrėti perrašymus failų nekeičiant |
| `--help` | Rodyti trumpąją naudojimo instrukciją |

---

## Išėjimo kodai

Greph vadovaujasi grep / ripgrep konvencijomis:

| Kodas | Reikšmė |
|---|---|
| `0` | Rastas bent vienas atitikmuo (arba, perrašymo atveju, pakeistas bent vienas failas) |
| `1` | Atitikmenų nerasta |
| `2` | Naudojimo klaida arba vykdymo triktis (netinkami argumentai, trūkstamas indeksas, analizės klaida `--strict-parse` režimu) |