# rg-Kompatibilität

`vendor/bin/rg` ist ein Kompatibilitätswrapper im Stil von ripgrep. Er akzeptiert die am häufigsten verwendeten ripgrep-Optionen, durchläuft den Dateibaum wie ripgrep und gibt passende Ergebnisse aus. Die geprüfte Funktionsabdeckung wurde anhand von Testläufen mit der Upstream-Binärdatei `rg` ermittelt und ist unter [Erweitert / Funktionsmatrix](https://greph.inline0.dev/de/docs/advanced/feature-matrix) dokumentiert.

Der Wrapper übersetzt CLI-Optionen direkt; die Suche selbst erledigt dieselbe Engine `Greph\Text\TextSearcher`, die auch `vendor/bin/greph` verwendet.

## Wann du ihn verwenden solltest

Verwende den Wrapper, wenn:

- Du bereits ein Tool, einen Agenten oder ein Skript hast, das `rg` aufruft.
- Du einen direkten Ersatz suchst, der auch in Umgebungen funktioniert, in denen du ripgrep selbst nicht installieren kannst (Shared Hosting, gehärtete Container, eingeschränkte PaaS).
- Du die Bedienung von ripgrep auf einer Infrastruktur nutzen möchtest, auf der nur PHP verfügbar ist.

Verwende das native `vendor/bin/greph`, wenn:

- Du neuen Code schreibst und nicht die ripgrep-Form CLI benötigst.
- Du Zugriff auf native Optionen möchtest, die der Wrapper nicht bereitstellt (zum Beispiel den AST-Modus).

## Verwendung

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

Ein Aufruf ohne Argumente durchsucht `.` rekursiv:

```bash
./vendor/bin/rg -F "function"
```

`--files` listet mögliche Dateien auf, statt sie zu durchsuchen:

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## JSON-Ausgabe

`--json` gibt dieselben ereignisartigen Nutzdaten aus wie ripgrep:

```bash
./vendor/bin/rg --json -F "function walk" src/Greph.php
```

```json
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}
```

Zeitangaben in den `stats`-Objekten werden immer als null ausgegeben.

Dieses Schema erwarten nachgelagerte Tools, wenn sie die strukturierte Ausgabe von ripgrep aktivieren. Wenn du ein einfacheres Format möchtest, verwende stattdessen `vendor/bin/greph --json`.

## Geprüfte Funktionsabdeckung

Die folgenden Optionen wurden anhand von `rg` selbst in der [Funktionsmatrix](https://greph.inline0.dev/de/docs/advanced/feature-matrix) überprüft. Upstream-Binärdatei und Wrapper erzeugen bei jeder Prüfung gleichwertige Ausgaben. Hat eine Option eine Kurz- und Langform, verwendet die Prüfung eine davon; der Wrapper verarbeitet beide als dieselbe Option.

### Suchoptionen

- `-F`, `--fixed-strings`
- `-i`, `--ignore-case`
- `-w`, `--word-regexp`
- `-v`, `--invert-match`
- `-c`, `--count`
- `-l`, `--files-with-matches`
- `--files-without-match`
- `-I`, `--no-filename`
- `-H`, `--with-filename`
- `-n`, `--line-number`
- `-A N`, `--after-context N`
- `-B N`, `--before-context N`
- `-C N`, `--context N`
- `-m N`, `--max-count N`
- `-e P`, `--regexp P`

### Optionen für den Dateibaum

- `-L`, `--follow`
- `--glob GLOB`
- `--type NAME`
- `--type-not NAME`
- `--no-ignore`
- `--hidden`
- `--files`
- `--files --hidden`
- `--files --type NAME`

### Ausgabeoptionen

- `--json`

### Ohne Prüfung akzeptiert

Der Wrapper akzeptiert außerdem die folgenden Optionen, die bisher jedoch nicht durch eine Prüfung in der Funktionsmatrix abgedeckt sind:

- `-j N`, `--threads N` (Anzahl der Worker, siehe [Parallele Worker](https://greph.inline0.dev/de/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Einschränkungen

Der `rg`-Wrapper von Greph deckt die Such- und Dateibaumoptionen ab, die von den meisten Tools und Agenten verwendet werden. Die folgenden ripgrep-Funktionen stellt er derzeit nicht bereit:

- Mehrzeilige Regexe (`-U`, `--multiline`)
- Ersetzungen (`-r`, `--replace`) im Textmodus (verwende stattdessen `vendor/bin/greph` für AST-Umschreibungen)
- Benutzerdefinierte Typdefinitionen (`--type-add`, `--type-clear`)
- Optionen für die Zeichenkodierung (`-E`, `--encoding`)
- `--pre`-Filterskripte
- `--sort`, `--sortr`

Wenn dir eine fehlende Option auffällt, erstelle ein Issue mit der Prüfung, die du gegen Upstream-`rg` ausgeführt hast, und der erwarteten Ausgabe. Neue Funktionen werden zusammen mit ihren Referenzprüfungen hinzugefügt, sodass die geprüfte Funktionsabdeckung stetig wächst.

## Verhaltensgleichheit

Der Wrapper zielt auf Verhaltensgleichheit, nicht auf Byte-Gleichheit. Die Ausgabe ist zeilenweise gleichwertig, kann sich aber in optischen Details unterscheiden (Farbcodes, Kürzung an der Terminalbreite). Die Prüfungen der [Funktionsmatrix](https://greph.inline0.dev/de/docs/advanced/feature-matrix) kontrollieren die semantische Gleichwertigkeit, nicht bytegenaue Unterschiede.

Für Agenten und Tools, die die Ausgabe parsen, sind die relevanten Felder (Dateipfad, Zeilennummer, Inhalt, Position der Übereinstimmung) bei jeder geprüften Prüfung byteidentisch mit Upstream-`rg`.