# CLI-viite

Greph sisältää neljä suoritettavaa tiedostoa. Kaikilla neljällä on sama moottori; niiden erot koskevat niiden tarjoamaa käyttöliittymää.

| Suoritettava tiedosto | Käyttötarkoitus |
|---|---|
| `greph` | Natiivi tekstihaku, AST-haku ja AST-uudelleenkirjoitus |
| `greph-index` | Lämmitetty tekstihakemisto, AST-faktahakemisto ja välimuistissa oleva AST-haku |
| `rg` | ripgrep-tyylinen yhteensopivuuskerros |
| `sg` | ast-grep-tyylinen yhteensopivuuskerros |

Esimerkkien poluissa käytetään `./vendor/bin/<binary>`-tiedostoa, joka toimii, kun Greph 0.2.3 on asennettu riippuvuutena tai uudempi versio. Käytä `./bin/<binary>`-polkua, jos työskentelet arkistokloonista.

---

## `greph`

Natiivi tekstihaku, AST-haku ja AST-uudelleenkirjoitus.

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

Jos polku jätetään pois, haku tehdään nykyisestä hakemistosta.

### Tekstitila

Oletustila. Mallit ovat PCRE2-säännöllisiä lausekkeita, ellei `-F` ole asetettu.

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

Tulostusmuoto vastaa `grep -rn`-tulostusta:

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

### AST-tila

Otettu käyttöön asetuksella `-p`. Mallit kirjoitetaan tavallisena PHP-koodina, jossa käytetään `$VAR`- ja `$$$VARIADIC`-metamuuttujia. Katso täydellinen mallikieli kohdasta [Tilat / AST-haku](https://greph.inline0.dev/fi/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
```

### Uudelleenkirjoitustila

Otettu käyttöön yhdistämällä `-p` ja `-r`. Korvausmallissa käytetään samoja metamuuttujia kuin hakumallissa; talteen otetut solmut sijoitetaan mukaan nimensä perusteella.

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

### Asetukset

| Valitsin | Merkitys |
|---|---|
| `-F` | Kiinteän merkkijonon haku (ei säännöllistä lauseketta) |
| `-i` | Kirjainkoosta riippumaton täsmäytys |
| `-w` | Kokonaisen sanan täsmäytys |
| `-v` | Käännä täsmäytys |
| `-c` | Laske osumat tiedostoittain |
| `-l` | Luettele vain osumia sisältävien tiedostojen polut |
| `-L` | Luettele vain tiedostojen polut, joissa ei ole osumia |
| `-h` | Piilota tiedostonimien etuliitteet tekstitilassa |
| `-H` | Tulosta tiedostonimien etuliitteet aina tekstitilassa |
| `-n` | Näytä rivinumerot (oletus: käytössä) |
| `-A N` | Näytä N riviä kunkin osuman jälkeen |
| `-B N` | Näytä N riviä kunkin osuman ennen |
| `-C N` | Näytä N kontekstiriviä kunkin osuman ympäriltä |
| `-m N` | Lopeta N osuman jälkeen tiedostoa kohden |
| `-j N` | Käytä N rinnakkaista työntekijää |
| `-p PATTERN` | AST-hakumalli |
| `-r TEMPLATE` | AST-uudelleenkirjoitusmalli (edellyttää `-p`) |
| `--glob GLOB` | Sisällytä vain tiedostot, joiden polku vastaa GLOB-mallia |
| `--type NAME` | Sisällytä tiedostotyyppialias (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Jätä tiedostotyyppialias pois |
| `--lang NAME` | AST-kieli. Oletus: `php` |
| `--json` | Tuota JSON-tulostus |
| `--no-ignore` | Ohita `.gitignore`- ja `.grephignore`-säännöt |
| `--hidden` | Sisällytä piilotetut tiedostot |
| `--dry-run` | Tulosta uudelleenkirjoitukset tallentamatta tiedostoja |
| `--interactive` | Vahvista jokainen uudelleenkirjoitettu tiedosto |
| `--help` | Näytä käyttöohje lyhyesti |

---

## `greph-index`

Lämmitetty tekstihakemisto, AST-faktahakemisto ja välimuistissa oleva AST-haku.

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

### Teksti-indeksi

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

Teksti-indeksi on lämmitetty trigrammi- ja tunnisteosumien tietovarasto. Se sijaitsee indeksoidun juurihakemiston polussa `.greph-index/` oletusarvoisesti.

### Indeksijoukot

Indeksijoukot kokoavat toistuvat usean indeksin työnkulut nimetyksi luetteloksi:

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

Oletusarvoinen luettelotiedosto on `.greph-index-set.json`. Kukin merkintä osoittaa juureen, tilaan ja elinkaariprofiiliin. `set build` ja `set refresh` käsittelevät käytössä olevia merkintöjä; `set search` suorittaa haun valituissa merkinnöissä ja poistaa päällekkäiset osumat.

### AST-faktahakemisto

```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-faktahakemisto poimii solmutason faktoja (kutsut, ilmentymien luonnit, luokat, metodit) kyseltävään tietovarastoon. Haut tehdään ensin O(log n) faktan avaimella ja tarkistetaan sitten lähdekoodista. Oletustallennuspolku on `.greph-ast-index/`.

### AST-välimuisti

```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-välimuisti tallentaa jäsennetyt puut levylle, jolloin haut ohittavat jäsentimen kokonaan. Oletustallennuspolku on `.greph-ast-cache/`.

### Asetukset

Tekstihaun asetukset vastaavat `greph`-valitsimia (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Lisävalitsimet:

| Valitsin | Merkitys |
|---|---|
| `--index-dir DIR` | Käytä muuta kuin oletusarvoista lämmitettyä indeksihakemistoa. Voidaan toistaa usean indeksin haussa ja tilastoissa. |
| `--lifecycle PROFILE` | Koontikäytäntö: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Tilapäivityksen tiedostokynnys |
| `--auto-refresh-max-bytes N` | Tilapäivityksen tavukynnys |
| `--manifest FILE` | Lataa indeksijoukon luettelo. Oletus: `.greph-index-set.json` |
| `--mode MODE` | Rajaa joukkotoiminnot arvoihin `text`, `ast-index` tai `ast-cache` |
| `--index NAME` | Rajaa joukkotoiminnot nimettyyn luettelomerkintään. Voidaan toistaa. |
| `--show-index-origin` | Lisää lämmitetyn monen indeksin tai joukon tulosteen alkuun vastaavan indeksimerkinnän nimi |
| `--trace-plan` | Tulosta lämmitetyn suunnittelijan diagnostiikkatiedot kohteeseen `stderr` |
| `--dry-refresh` | Tilassa `stats` ilmoita, mitä lämmitetty haku tekisi muuttamatta mitään |
| `--lang NAME` | AST-kieli hauille `ast-index` / `ast-cache`. Oletus: `php` |
| `-j N`, `--jobs N` | AST-läpikäyntien työntekijämäärä |
| `-l`, `--files-with-matches` | Luettele vain osumia sisältävien tiedostojen polut (AST-tila) |
| `--strict-parse` | Keskeytä jäsennysvirheen ilmetessä äläkä ohita sitä |
| `--fallback MODE` | Puuttuvan indeksin käsittely: `fail` (oletus) tai `scan` |
| `--help` | Näytä käyttöohje lyhyesti |

---

## `rg`

ripgrep-tyylinen yhteensopivuuskerros. Tukee yleisimmin käytettyjä ripgrep-valitsimia. Vahvistetut ominaisuudet on julkaistu [ominaisuusmatriisissa](https://greph.inline0.dev/fi/docs/advanced/feature-matrix).

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

### Esimerkkejä

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

### Tuetut asetukset

| Valitsin | Merkitys |
|---|---|
| `-F`, `--fixed-strings` | Kiinteän merkkijonon haku |
| `-i`, `--ignore-case` | Kirjainkoosta riippumaton haku |
| `-w`, `--word-regexp` | Kokonaisen sanan haku |
| `-v`, `--invert-match` | Käännä osumat |
| `-c`, `--count` | Laske osumarivit |
| `-l`, `--files-with-matches` | Luettele osumia sisältävät tiedostot |
| `--files-without-match` | Luettele tiedostot, joissa ei ole osumia |
| `-I`, `--no-filename` | Piilota tiedostonimien etuliitteet |
| `-H`, `--with-filename` | Tulosta tiedostonimien etuliitteet aina |
| `-n`, `--line-number` | Näytä rivinumerot |
| `-A N`, `--after-context N` | Näytä N riviä kunkin osuman jälkeen |
| `-B N`, `--before-context N` | Näytä N riviä kunkin osuman ennen |
| `-C N`, `--context N` | Näytä N riviä ennen kutakin osumaa ja sen jälkeen |
| `-m N`, `--max-count N` | Lopeta N osuman jälkeen tiedostoa kohden |
| `-j N`, `--threads N` | Käytä N rinnakkaista työntekijää |
| `-e P`, `--regexp P` | Hakumalli |
| `-L`, `--follow` | Seuraa symbolisia linkkejä |
| `--glob GLOB` | Sisällytä vain tiedostot, joiden polku vastaa GLOB-mallia |
| `--type NAME` | Sisällytä tiedostotyyppi |
| `--type-not NAME` | Jätä tiedostotyyppi pois |
| `--json` | Tuota ripgrep-tyylisiä JSON-tapahtumia |
| `--no-ignore` | Ohita `.gitignore`- ja `.grephignore`-säännöt |
| `--hidden` | Sisällytä piilotetut tiedostot |
| `--files` | Luettele ehdokastiedostot haun sijaan |
| `--help` | Näytä käyttöohje lyhyesti |

---

## `sg`

ast-grep-tyylinen yhteensopivuuskerros. Tukee yleisimmin käytettyjä ast-grep-valitsimia. Vahvistetut ominaisuudet on julkaistu [ominaisuusmatriisissa](https://greph.inline0.dev/fi/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` on kanoninen ast-grep-verbi. `scan` ja `rewrite` ovat vain yhteensopivuuskerroksen aliaksia, jotka vastaavat yleistä käyttötapaa. Myös pelkkä komento (`sg --pattern ... .`) toimii kertaluonteisena hakuna.

### Esimerkkejä

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

### Tuetut asetukset

| Valitsin | Merkitys |
|---|---|
| `-p`, `--pattern PATTERN` | AST-malli |
| `-r`, `--rewrite TEMPLATE` | Uudelleenkirjoitusmalli |
| `-l`, `--lang NAME` | AST-kieli. Oletus: `php` |
| `-j`, `--threads N` | Käytä N rinnakkaista työntekijää |
| `-i`, `--interactive` | Vahvista jokainen uudelleenkirjoitus |
| `-U`, `--update-all` | Käytä uudelleenkirjoituksia ilman vahvistusta |
| `--files-with-matches` | Tulosta vain osumia sisältävien tiedostojen polut |
| `--json[=STYLE]` | Tuota JSON-tulostus. TYYLI = `pretty`, `stream` tai `compact` |
| `--no-ignore [MODE]` | Ohita repositorion ohitussäännöt |
| `--hidden` | Sisällytä piilotetut tiedostot |
| `--glob GLOB`, `--globs GLOB` | Sisällytä vain tiedostot, joiden polku vastaa GLOB-mallia |
| `--type NAME` | Sisällytä tiedostotyyppi |
| `--type-not NAME` | Jätä tiedostotyyppi pois |
| `--dry-run` | Esikatsele uudelleenkirjoitukset tallentamatta tiedostoja |
| `--help` | Näytä käyttöohje lyhyesti |

---

## Palautuskoodit

Greph noudattaa grepin / ripgrep-käytäntöjä:

| Koodi | Merkitys |
|---|---|
| `0` | Vähintään yksi osuma löytyi (tai uudelleenkirjoituksessa vähintään yhtä tiedostoa muutettiin) |
| `1` | Osumia ei löytynyt |
| `2` | Käyttövirhe tai suorituksenaikainen virhe (virheelliset argumentit, puuttuva indeksi, jäsennysvirhe tilassa `--strict-parse`) |