# CLI Referenz

Greph enthält vier ausführbare Dateien. Alle vier verwenden dieselbe Engine; sie unterscheiden sich in der angebotenen Oberfläche.

| Programmdatei | Zweck |
|---|---|
| `greph` | Native Textsuche, AST-Suche und AST-Umschreibung |
| `greph-index` | Aufgewärmter Textindex, AST-Faktenindex und Suche mit AST-Cache |
| `rg` | Kompatibilitätswrapper im Stil von ripgrep |
| `sg` | Kompatibilitätswrapper im Stil von ast-grep |

Alle Pfade in den Beispielen verwenden `./vendor/bin/<binary>`. Das funktioniert mit Greph 0.2.3 oder höher als installierter Abhängigkeit. Ersetze `./bin/<binary>`, wenn du mit einem Klon des Repositorys arbeitest.

---

## `greph`

Native Textsuche, AST-Suche und AST-Umschreibung.

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

Wenn kein Pfad angegeben ist, wird das aktuelle Verzeichnis durchsucht.

### Textmodus

Standardmodus. Muster sind PCRE2-Regexe, sofern `-F` nicht gesetzt ist.

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

Das Ausgabeformat entspricht `grep -rn`:

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

### AST-Modus

Wird durch `-p` aktiviert. Muster werden als gewöhnliche PHP mit Metavariablen `$VAR` und `$$$VARIADIC` geschrieben. Die vollständige Mustersyntax findest du unter [Modi / AST-Suche](https://greph.inline0.dev/de/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
```

### Umschreibmodus

Wird durch die Kombination von `-p` und `-r` aktiviert. Die Ersetzungsvorlage verwendet dieselben Metavariablen wie das Suchmuster; erfasste Knoten werden anhand ihres Namens eingefügt.

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

### Optionen

| Option | Bedeutung |
|---|---|
| `-F` | Suche nach festem Text (kein Regex) |
| `-i` | Groß- und Kleinschreibung ignorieren |
| `-w` | Ganzes Wort abgleichen |
| `-v` | Übereinstimmungen umkehren |
| `-c` | Übereinstimmungen pro Datei zählen |
| `-l` | Nur Pfade übereinstimmender Dateien auflisten |
| `-L` | Nur Pfade nicht übereinstimmender Dateien auflisten |
| `-h` | Dateinamenpräfixe im Textmodus unterdrücken |
| `-H` | Dateinamenpräfixe im Textmodus immer ausgeben |
| `-n` | Zeilennummern anzeigen (Standard: ein) |
| `-A N` | N Zeilen nach jeder Übereinstimmung anzeigen |
| `-B N` | N Zeilen vor jeder Übereinstimmung anzeigen |
| `-C N` | N Kontextzeilen vor und nach jeder Übereinstimmung anzeigen |
| `-m N` | Nach N Übereinstimmungen pro Datei abbrechen |
| `-j N` | N parallele Worker verwenden |
| `-p PATTERN` | AST-Suchmuster |
| `-r TEMPLATE` | AST-Umschreibungsvorlage (erfordert `-p`) |
| `--glob GLOB` | Nur Dateien einbeziehen, deren Pfade auf GLOB passen |
| `--type NAME` | Einen Dateityp-Alias einbeziehen (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Einen Dateityp-Alias ausschließen |
| `--lang NAME` | AST-Sprache. Standard: `php` |
| `--json` | JSON-Ausgabe erzeugen |
| `--no-ignore` | Regeln für `.gitignore` und `.grephignore` ignorieren |
| `--hidden` | Versteckte Dateien einbeziehen |
| `--dry-run` | Umschreibungen ausgeben, ohne Dateien zu schreiben |
| `--interactive` | Jede umgeschriebene Datei bestätigen lassen |
| `--help` | Inline-Hilfe anzeigen |

---

## `greph-index`

Aufgewärmter Textindex, AST-Faktenindex und Suche mit AST-Cache.

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

### Textindex

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

Der Textindex ist ein aufgewärmter Speicher für Trigramme und Beleglisten von Bezeichnern. Standardmäßig liegt er unter `.greph-index/` im indexierten Stammverzeichnis.

### Indexgruppen

Mit Indexgruppen werden wiederholte Abläufe mit mehreren Indizes in einem benannten Manifest zusammengefasst:

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

Die standardmäßige Manifestdatei ist `.greph-index-set.json`. Jeder Eintrag verweist auf ein Stammverzeichnis, einen Modus und ein Lebenszyklusprofil. `set build` und `set refresh` arbeiten mit den aktivierten Einträgen; `set search` durchsucht die ausgewählten Einträge und entfernt doppelte, überlappende Übereinstimmungen.

### AST-Faktenindex

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

Der AST-Faktenindex extrahiert Fakten auf Knotenebene (Aufrufe, Instanziierungen, Klassen, Methoden) in einen durchsuchbaren Speicher. Suchanfragen werden anhand des Faktenschlüssels mit O(log n) ausgeführt und anschließend mit der Quelle abgeglichen. Standardmäßig gespeichert unter `.greph-ast-index/`.

### AST-Cache

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

Der AST-Cache speichert geparste Bäume auf der Festplatte, damit Suchvorgänge den Parser vollständig überspringen. Standardmäßig gespeichert unter `.greph-ast-cache/`.

### Optionen

Die Textsuchoptionen entsprechen den Optionen von `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Zusätzliche Optionen:

| Option | Bedeutung |
|---|---|
| `--index-dir DIR` | Ein abweichendes Verzeichnis für den aufgewärmten Index verwenden. Für die Suche mit mehreren Indizes und Statistiken wiederholbar. |
| `--lifecycle PROFILE` | Erstellungsrichtlinie: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Dateischwellenwert für opportunistische Aktualisierung |
| `--auto-refresh-max-bytes N` | Byte-Schwellenwert für opportunistische Aktualisierung |
| `--manifest FILE` | Indexgruppen-Manifest laden. Standard: `.greph-index-set.json` |
| `--mode MODE` | Gruppenoperationen auf `text`, `ast-index` oder `ast-cache` beschränken |
| `--index NAME` | Gruppenoperationen auf einen benannten Manifesteintrag beschränken. Wiederholbar. |
| `--show-index-origin` | Ausgabe der Suche mit aufgewärmtem Mehrfachindex oder Indexgruppe mit dem Namen des passenden Indexeintrags präfixieren |
| `--trace-plan` | Diagnoseinformationen zum aufgewärmten Suchplan an `stderr` ausgeben |
| `--dry-refresh` | In `stats` melden, was eine aufgewärmte Suche tun würde, ohne etwas zu ändern |
| `--lang NAME` | AST-Sprache für `ast-index`-/`ast-cache`-Suchen. Standard: `php` |
| `-j N`, `--jobs N` | Worker für AST-Scans |
| `-l`, `--files-with-matches` | Nur Pfade übereinstimmender Dateien auflisten (AST-Modus) |
| `--strict-parse` | Bei Parse-Fehlern abbrechen, statt sie zu überspringen |
| `--fallback MODE` | Verhalten bei fehlendem Index: `fail` (Standard) oder `scan` |
| `--help` | Inline-Hilfe anzeigen |

---

## `rg`

Kompatibilitätswrapper im Stil von ripgrep. Unterstützt die am häufigsten verwendeten ripgrep-Optionen. Die geprüfte Funktionsabdeckung ist in der [Funktionsmatrix](https://greph.inline0.dev/de/docs/advanced/feature-matrix) veröffentlicht.

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

### Beispiele

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

### Unterstützte Optionen

| Option | Bedeutung |
|---|---|
| `-F`, `--fixed-strings` | Suche nach festem Text |
| `-i`, `--ignore-case` | Suche ohne Beachtung der Groß- und Kleinschreibung |
| `-w`, `--word-regexp` | Suche nach ganzen Wörtern |
| `-v`, `--invert-match` | Übereinstimmungen umkehren |
| `-c`, `--count` | Übereinstimmende Zeilen zählen |
| `-l`, `--files-with-matches` | Übereinstimmende Dateien auflisten |
| `--files-without-match` | Nicht übereinstimmende Dateien auflisten |
| `-I`, `--no-filename` | Dateinamenpräfixe unterdrücken |
| `-H`, `--with-filename` | Dateinamenpräfixe immer ausgeben |
| `-n`, `--line-number` | Zeilennummern anzeigen |
| `-A N`, `--after-context N` | N Zeilen nach jeder Übereinstimmung anzeigen |
| `-B N`, `--before-context N` | N Zeilen vor jeder Übereinstimmung anzeigen |
| `-C N`, `--context N` | N Zeilen vor und nach jeder Übereinstimmung anzeigen |
| `-m N`, `--max-count N` | Nach N Übereinstimmungen pro Datei abbrechen |
| `-j N`, `--threads N` | N parallele Worker verwenden |
| `-e P`, `--regexp P` | Suchmuster |
| `-L`, `--follow` | Symlinks folgen |
| `--glob GLOB` | Nur Dateien einbeziehen, deren Pfade auf GLOB passen |
| `--type NAME` | Einen Dateityp einbeziehen |
| `--type-not NAME` | Einen Dateityp ausschließen |
| `--json` | JSON-Ereignisse im ripgrep-Format ausgeben |
| `--no-ignore` | Regeln für `.gitignore` und `.grephignore` ignorieren |
| `--hidden` | Versteckte Dateien einbeziehen |
| `--files` | Kandidatendateien auflisten, statt zu suchen |
| `--help` | Inline-Hilfe anzeigen |

---

## `sg`

Kompatibilitätswrapper im Stil von ast-grep. Unterstützt die am häufigsten verwendeten ast-grep-Optionen. Die geprüfte Funktionsabdeckung ist in der [Funktionsmatrix](https://greph.inline0.dev/de/docs/advanced/feature-matrix) veröffentlicht.

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` ist das kanonische ast-grep-Verb. `scan` und `rewrite` sind nur im Wrapper verfügbare Aliase, die der üblichen Verwendung entsprechen. Ein Aufruf ohne Argumente (`sg --pattern ... .`) funktioniert ebenfalls als einmalige Suche.

### Beispiele

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

### Unterstützte Optionen

| Option | Bedeutung |
|---|---|
| `-p`, `--pattern PATTERN` | AST-Muster |
| `-r`, `--rewrite TEMPLATE` | Umschreibungsvorlage |
| `-l`, `--lang NAME` | AST-Sprache. Standard: `php` |
| `-j`, `--threads N` | N parallele Worker verwenden |
| `-i`, `--interactive` | Jede Umschreibung bestätigen lassen |
| `-U`, `--update-all` | Umschreibungen ohne Bestätigung anwenden |
| `--files-with-matches` | Nur Dateipfade mit Übereinstimmungen ausgeben |
| `--json[=STYLE]` | Ausgabe im Format JSON erzeugen. STYLE = `pretty`, `stream` oder `compact` |
| `--no-ignore [MODE]` | Repository-Ignorierregeln ignorieren |
| `--hidden` | Versteckte Dateien einbeziehen |
| `--glob GLOB`, `--globs GLOB` | Nur Dateien einbeziehen, deren Pfade auf GLOB passen |
| `--type NAME` | Einen Dateityp einbeziehen |
| `--type-not NAME` | Einen Dateityp ausschließen |
| `--dry-run` | Umschreibungen in der Vorschau anzeigen, ohne Dateien zu schreiben |
| `--help` | Inline-Hilfe anzeigen |

---

## Exit-Codes

Greph folgt den Konventionen von grep / ripgrep:

| Code | Bedeutung |
|---|---|
| `0` | Mindestens eine Übereinstimmung gefunden (oder bei Umschreibungen mindestens eine Datei geändert) |
| `1` | Keine Übereinstimmungen gefunden |
| `2` | Fehler bei der Verwendung oder Laufzeit (ungültige Argumente, fehlender Index, Parse-Fehler im Modus `--strict-parse`) |