# CLI uzziņu rokasgrāmata

Greph ietver četrus izpildāmos failus. Visiem četriem ir viens un tas pats dzinis; atšķiras tikai to piedāvātā saskarne.

| Binārais fails | Mērķis |
|---|---|
| `greph` | Vietējā teksta meklēšana, AST meklēšana un AST pārrakstīšana |
| `greph-index` | Uzsildīts teksta indekss, AST faktu indekss un kešota AST meklēšana |
| `rg` | Ar ripgrep saderīgs iesaiņotājs |
| `sg` | Ar ast-grep saderīgs iesaiņotājs |

Visos piemēros izmantoti ceļi `./vendor/bin/<binary>` formātā. Tie darbojas, ja Greph 0.2.3 ir instalēts kā atkarība vai vēlāk tiek instalēts. Ja strādājat ar repozitorija klonu, aizstājiet to ar `./bin/<binary>`.

---

## `greph`

Vietējā teksta meklēšana, AST meklēšana un AST pārrakstīšana.

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

Ja ceļš nav norādīts, meklēšana tiek veikta pašreizējā mapē.

### Teksta režīms

Noklusējuma režīms. Raksti ir PCRE2 regulārās izteiksmes, ja vien nav iestatīts `-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
```

Izvades formāts atbilst `grep -rn`:

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

### AST režīms

Aktivizē ar `-p`. Raksti tiek veidoti kā parasts PHP, izmantojot metavariablos `$VAR` un `$$$VARIADIC`. Pilnu raksta gramatiku skatiet sadaļā [AST režīmi / AST meklēšana](https://greph.inline0.dev/lv/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ārrakstīšanas režīms

Aktivizē, apvienojot `-p` ar `-r`. Aizvietošanas veidne izmanto tos pašus metavariablos kā meklēšanas raksts; uztvertie mezgli tiek ievietoti pēc nosaukuma.

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

### Opcijas

| Karodziņš | Nozīme |
|---|---|
| `-F` | Meklēšana pēc precīzas virknes (bez regex) |
| `-i` | Meklēšana, neņemot vērā reģistru |
| `-w` | Meklēšana pēc pilna vārda |
| `-v` | Apgriezt atbilstības nosacījumu |
| `-c` | Saskaitīt atbilstības katrā failā |
| `-l` | Norādīt tikai atbilstošo failu ceļus |
| `-L` | Norādīt tikai neatbilstošo failu ceļus |
| `-h` | Teksta režīmā nerādīt failu nosaukumu prefiksus |
| `-H` | Teksta režīmā vienmēr rādīt failu nosaukumu prefiksus |
| `-n` | Rādīt rindu numurus (pēc noklusējuma ieslēgts) |
| `-A N` | Rādīt N rindas pēc katras atbilstības |
| `-B N` | Rādīt N rindas pirms katras atbilstības |
| `-C N` | Rādīt N konteksta rindas pirms un pēc katras atbilstības |
| `-m N` | Pārtraukt pēc N atbilstībām katrā failā |
| `-j N` | Izmantot N paralēlos darbplūsmu izpildītājus |
| `-p PATTERN` | AST meklēšanas raksts |
| `-r TEMPLATE` | AST pārrakstīšanas veidne (nepieciešams `-p`) |
| `--glob GLOB` | Iekļaut tikai failus, kuru ceļi atbilst GLOB |
| `--type NAME` | Iekļaut faila tipa aizstājvārdu (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Izslēgt faila tipa aizstājvārdu |
| `--lang NAME` | AST valoda. Noklusējums: `php` |
| `--json` | Izvadīt JSON formāta izvadi |
| `--no-ignore` | Ignorēt `.gitignore` un `.grephignore` noteikumus |
| `--hidden` | Iekļaut slēptos failus |
| `--dry-run` | Parādīt pārrakstījumus, nemainot failus |
| `--interactive` | Apstiprināt katru failu, kurā veikta pārrakstīšana |
| `--help` | Rādīt lietošanas informāciju iekļautajā saskarnē |

---

## `greph-index`

Uzsildīts teksta indekss, AST faktu indekss un kešota AST meklēšana.

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

### Teksta indekss

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

Teksta indekss ir uzsildīta trigrammu un identifikatoru ierakstu krātuve. Pēc noklusējuma tā atrodas mapē `.greph-index/` indeksētajā saknes mapē.

### Indeksu kopas

Indeksu kopas ļauj atkārtotas vairāku indeksu darbplūsmas aprakstīt nosauktā 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)' .
```

Noklusējuma manifesta fails ir `.greph-index-set.json`. Katrs ieraksts norāda saknes mapi, režīmu un dzīves cikla profilu. `set build` un `set refresh` darbojas ar iespējotajiem ierakstiem; `set search` vienlaikus apstrādā atlasītos ierakstus un izslēdz dublējošās atbilstības.

### AST faktu indekss

```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 faktu indekss izgūst mezglu līmeņa faktus (izsaukumus, instancēšanas, klases, metodes) un saglabā tos vaicājumiem pieejamā krātuvē. Vispirms tiek veikta O(log n) meklēšana pēc fakta atslēgas, pēc tam rezultāti tiek pārbaudīti, salīdzinot tos ar avotu. Pēc noklusējuma dati tiek glabāti mapē `.greph-ast-index/`.

### AST kešatmiņa

```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 kešatmiņa saglabā diskā parsētos kokus, lai meklēšanas laikā varētu pilnībā izlaist parsētāju. Pēc noklusējuma dati tiek glabāti mapē `.greph-ast-cache/`.

### Opcijas

Teksta meklēšanas opcijas atbilst `greph` karodziņu kopai (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Papildu karodziņi:

| Karodziņš | Nozīme |
|---|---|
| `--index-dir DIR` | Izmantot uzsildītu indeksu mapē, kas nav noklusējuma mape. Atkārtojams vairāku indeksu meklēšanai un statistikai. |
| `--lifecycle PROFILE` | Veidošanas politika: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Failu skaita slieksnis neregulārai atsvaidzināšanai |
| `--auto-refresh-max-bytes N` | Baitu slieksnis neregulārai atsvaidzināšanai |
| `--manifest FILE` | Ielādēt indeksu kopas manifestu. Noklusējums: `.greph-index-set.json` |
| `--mode MODE` | Ierobežot kopas darbības līdz `text`, `ast-index` vai `ast-cache` |
| `--index NAME` | Ierobežot kopas darbības līdz nosauktam manifesta ierakstam. Atkārtojams. |
| `--show-index-origin` | Vairāku uzsildītu indeksu vai kopas izvadei pievienot prefiksu ar atbilstošā indeksa ieraksta nosaukumu |
| `--trace-plan` | Izvadīt uzsildītā plānotāja diagnostikas informāciju uz `stderr` |
| `--dry-refresh` | Ar `stats` ziņot, ko veiktu uzsildīta meklēšana, neko nemainot |
| `--lang NAME` | AST valoda `ast-index` / `ast-cache` meklēšanai. Noklusējums: `php` |
| `-j N`, `--jobs N` | Darbplūsmu izpildītāji AST skenēšanai |
| `-l`, `--files-with-matches` | Norādīt tikai atbilstošo failu ceļus (AST režīms) |
| `--strict-parse` | Kļūdas gadījumā neizlaist failus ar parsēšanas kļūdām |
| `--fallback MODE` | Rīcība, ja trūkst indeksa: `fail` (noklusējums) vai `scan` |
| `--help` | Rādīt lietošanas informāciju iekļautajā saskarnē |

---

## `rg`

ripgrep tipa saderības iesaiņotājs. Atbalsta visbiežāk lietotos ripgrep karodziņus. Pārbaudītā funkcionalitāte publicēta sadaļā [funkciju matrica](https://greph.inline0.dev/lv/docs/advanced/feature-matrix).

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

### Piemēri

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

### Atbalstītās opcijas

| Karodziņš | Nozīme |
|---|---|
| `-F`, `--fixed-strings` | Meklēšana pēc precīzas virknes |
| `-i`, `--ignore-case` | Meklēšana, neņemot vērā reģistru |
| `-w`, `--word-regexp` | Meklēšana pēc pilna vārda |
| `-v`, `--invert-match` | Apgriezt atbilstības nosacījumu |
| `-c`, `--count` | Saskaitīt atbilstošās rindas |
| `-l`, `--files-with-matches` | Norādīt atbilstošos failus |
| `--files-without-match` | Norādīt neatbilstošos failus |
| `-I`, `--no-filename` | Nerādīt failu nosaukumu prefiksus |
| `-H`, `--with-filename` | Vienmēr rādīt failu nosaukumu prefiksus |
| `-n`, `--line-number` | Rādīt rindu numurus |
| `-A N`, `--after-context N` | Rādīt N rindas pēc katras atbilstības |
| `-B N`, `--before-context N` | Rādīt N rindas pirms katras atbilstības |
| `-C N`, `--context N` | Rādīt N rindas pirms un pēc katras atbilstības |
| `-m N`, `--max-count N` | Pārtraukt pēc N atbilstībām katrā failā |
| `-j N`, `--threads N` | Izmantot N paralēlos darbplūsmu izpildītājus |
| `-e P`, `--regexp P` | Meklēšanas raksts |
| `-L`, `--follow` | Sekot simboliskajām saitēm |
| `--glob GLOB` | Iekļaut tikai failus, kuru ceļi atbilst GLOB |
| `--type NAME` | Iekļaut faila tipu |
| `--type-not NAME` | Izslēgt faila tipu |
| `--json` | Izvadīt ripgrep tipa JSON notikumus |
| `--no-ignore` | Ignorēt `.gitignore` un `.grephignore` noteikumus |
| `--hidden` | Iekļaut slēptos failus |
| `--files` | Meklēšanas vietā uzskaitīt kandidātfailus |
| `--help` | Rādīt lietošanas informāciju iekļautajā saskarnē |

---

## `sg`

ast-grep tipa saderības iesaiņotājs. Atbalsta visbiežāk lietotos ast-grep karodziņus. Pārbaudītā funkcionalitāte publicēta sadaļā [funkciju matrica](https://greph.inline0.dev/lv/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` ir kanoniskā ast-grep komanda. `scan` un `rewrite` ir tikai iesaiņotāja aizstājvārdi, kas atbilst ierastajam lietojumam. Var izmantot arī vienkāršu izsaukumu (`sg --pattern ... .`), lai veiktu vienreizēju meklēšanu.

### Piemēri

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

### Atbalstītās opcijas

| Karodziņš | Nozīme |
|---|---|
| `-p`, `--pattern PATTERN` | AST raksts |
| `-r`, `--rewrite TEMPLATE` | Pārrakstīšanas veidne |
| `-l`, `--lang NAME` | AST valoda. Noklusējums: `php` |
| `-j`, `--threads N` | Izmantot N paralēlos darbplūsmu izpildītājus |
| `-i`, `--interactive` | Apstiprināt katru pārrakstīšanu |
| `-U`, `--update-all` | Veikt pārrakstīšanu bez apstiprinājuma |
| `--files-with-matches` | Norādīt tikai to failu ceļus, kuros ir atbilstības |
| `--json[=STYLE]` | Izvadīt JSON izvadi. STILS = `pretty`, `stream` vai `compact` |
| `--no-ignore [MODE]` | Ignorēt repozitorija ignorēšanas noteikumus |
| `--hidden` | Iekļaut slēptos failus |
| `--glob GLOB`, `--globs GLOB` | Iekļaut tikai failus, kuru ceļi atbilst GLOB |
| `--type NAME` | Iekļaut faila tipu |
| `--type-not NAME` | Izslēgt faila tipu |
| `--dry-run` | Priekšskatīt pārrakstījumus, nemainot failus |
| `--help` | Rādīt lietošanas informāciju iekļautajā saskarnē |

---

## Izejas kodi

Greph ievēro grep / ripgrep konvencijas:

| Kods | Nozīme |
|---|---|
| `0` | Atrasta vismaz viena atbilstība (vai pārrakstīšanas gadījumā mainīts vismaz viens fails) |
| `1` | Nav atrasta neviena atbilstība |
| `2` | Lietošanas kļūda vai izpildlaika kļūme (nepareizi argumenti, trūkst indeksa, parsēšanas kļūda režīmā `--strict-parse`) |