CLI Referenz

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu d105217

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.

Shell

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.

Shell

# 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.

Shell

./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.

Shell

# 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.

Shell

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

Shell

# 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:

Shell

./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

Shell

./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

Shell

./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 veröffentlicht.

Shell

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

Beispiele

Shell

./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 veröffentlicht.

Shell

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

Shell

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