Dokumentacja CLI

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: d105217

Greph zawiera cztery pliki wykonywalne. Wszystkie korzystają z tego samego silnika; różnią się udostępnianym interfejsem.

Plik wykonywalny	Zastosowanie
`greph`	Natywne wyszukiwanie tekstu, wyszukiwanie AST i przepisywanie AST
`greph-index`	Rozgrzany indeks tekstowy, indeks faktów AST i buforowane wyszukiwanie AST
`rg`	Warstwa zgodności w stylu ripgrep
`sg`	Warstwa zgodności w stylu ast-grep

W przykładach użyto ścieżki ./vendor/bin/<binary>, która działa z Greph 0.2.3 lub nowszą wersją zainstalowaną jako zależność. Jeśli pracujesz na klonie repozytorium, zastąp ją przez ./bin/<binary>.

`greph`

Natywne wyszukiwanie tekstu, wyszukiwanie AST i przepisywanie AST.

Powłoka

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

Jeśli pominięto ścieżkę, wyszukiwanie odbywa się w bieżącym katalogu.

Tryb tekstowy

Tryb domyślny. Wzorce są wyrażeniami regularnymi PCRE2, chyba że ustawiono -F.

Powłoka

# 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

Format wyjściowy odpowiada formatowi grep -rn:

Text

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

Tryb AST

Aktywowany przez -p. Wzorce zapisuje się jako zwykłe PHP z metazmiennymi $VAR i $$$VARIADIC. Pełną składnię wzorców opisano w sekcji Tryby / wyszukiwanie AST.

Powłoka

./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

Tryb przepisywania

Aktywowany przez połączenie -p z -r. Szablon zastępczy używa tych samych metazmiennych co wzorzec wyszukiwania; przechwycone węzły są wstawiane według nazwy.

Powłoka

# 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

Opcje

Flaga	Znaczenie
`-F`	Wyszukiwanie stałego ciągu (bez wyrażeń regularnych)
`-i`	Dopasowywanie bez rozróżniania wielkości liter
`-w`	Dopasowywanie całych słów
`-v`	Odwrócenie dopasowania
`-c`	Zliczanie dopasowań w każdym pliku
`-l`	Wyświetlanie tylko ścieżek pasujących plików
`-L`	Wyświetlanie tylko ścieżek niepasujących plików
`-h`	Ukrywanie prefiksów nazw plików w trybie tekstowym
`-H`	Zawsze wyświetlanie prefiksów nazw plików w trybie tekstowym
`-n`	Wyświetlanie numerów wierszy (domyślnie: włączone)
`-A N`	Wyświetlanie N wierszy po każdym dopasowaniu
`-B N`	Wyświetlanie N wierszy przed każdym dopasowaniem
`-C N`	Wyświetlanie N wierszy kontekstu przed każdym dopasowaniem i po nim
`-m N`	Zatrzymanie po N dopasowaniach w każdym pliku
`-j N`	Użycie N równoległych procesów roboczych
`-p PATTERN`	Wzorzec wyszukiwania AST
`-r TEMPLATE`	Szablon przepisywania AST (wymaga `-p`)
`--glob GLOB`	Uwzględnianie tylko plików, których ścieżki pasują do GLOB
`--type NAME`	Uwzględnienie aliasu typu pliku (`php`, `js`, `md`, ...)
`--type-not NAME`	Wykluczenie aliasu typu pliku
`--lang NAME`	Język AST. Domyślnie: `php`
`--json`	Emitowanie danych wyjściowych JSON
`--no-ignore`	Ignorowanie reguł `.gitignore` i `.grephignore`
`--hidden`	Uwzględnianie ukrytych plików
`--dry-run`	Wyświetlanie przepisanych treści bez zapisywania plików
`--interactive`	Potwierdzanie każdego przepisanego pliku
`--help`	Wyświetlanie wbudowanej pomocy

`greph-index`

Rozgrzany indeks tekstowy, indeks faktów AST i buforowane wyszukiwanie AST.

Powłoka

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

Indeks tekstowy

Powłoka

# 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

Indeks tekstowy to rozgrzany magazyn trójek i postów identyfikatorów. Domyślnie znajduje się w .greph-index/ w indeksowanym katalogu głównym.

Zestawy indeksów

Zestawy indeksów pozwalają zastąpić powtarzane operacje na wielu indeksach nazwanym manifestem:

Powłoka

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

Domyślny plik manifestu to .greph-index-set.json. Każdy wpis wskazuje katalog główny, tryb i profil cyklu życia. set build i set refresh działają na włączonych wpisach; set search uruchamia operację dla wybranych wpisów i usuwa zduplikowane nakładające się wyniki.

Indeks faktów AST

Powłoka

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

Indeks faktów AST wyodrębnia fakty na poziomie węzłów (wywołania, instancje, klasy, metody) do przeszukiwalnego magazynu. Wyszukiwanie odbywa się przez O(log n) po kluczu faktu, a następnie wyniki są weryfikowane względem źródła. Domyślnie dane są przechowywane w .greph-ast-index/.

Bufor AST

Powłoka

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

Bufor AST zapisuje sparsowane drzewa na dysku, dzięki czemu wyszukiwanie całkowicie pomija parser. Domyślnie dane są przechowywane w .greph-ast-cache/.

Opcje

Opcje wyszukiwania tekstowego odpowiadają zestawowi flag greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Dodatkowe flagi:

Flaga	Znaczenie
`--index-dir DIR`	Użycie niestandardowego katalogu rozgrzanego indeksu. Można powtarzać przy wyszukiwaniu i wyświetlaniu statystyk z wielu indeksów.
`--lifecycle PROFILE`	Zasady budowania: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Próg liczby plików dla odświeżania przy okazji
`--auto-refresh-max-bytes N`	Próg bajtów dla odświeżania przy okazji
`--manifest FILE`	Wczytanie manifestu zestawu indeksów. Domyślnie: `.greph-index-set.json`
`--mode MODE`	Ograniczenie operacji na zestawie do `text`, `ast-index` lub `ast-cache`
`--index NAME`	Ograniczenie operacji na zestawie do wskazanego wpisu manifestu. Można powtarzać.
`--show-index-origin`	Dodanie na początku danych wyjściowych wyszukiwania lub zestawu wielu rozgrzanych indeksów nazwy pasującego wpisu indeksu
`--trace-plan`	Emitowanie diagnostyki planisty rozgrzanego indeksu do `stderr`
`--dry-refresh`	W `stats` raportowanie działania wyszukiwania z rozgrzanym indeksem bez wprowadzania zmian
`--lang NAME`	Język AST dla wyszukiwań `ast-index` / `ast-cache`. Domyślnie: `php`
`-j N`, `--jobs N`	Procesy robocze do skanowania AST
`-l`, `--files-with-matches`	Wyświetlanie tylko ścieżek pasujących plików (tryb AST)
`--strict-parse`	Zgłaszanie błędów parsowania zamiast ich pomijania
`--fallback MODE`	Zachowanie przy braku indeksu: `fail` (domyślnie) lub `scan`
`--help`	Wyświetlanie wbudowanej pomocy

`rg`

Warstwa zgodności w stylu ripgrep. Obsługuje najczęściej używane flagi ripgrep. Zweryfikowany zakres opisano w macierzy funkcji.

Powłoka

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

Przykłady

Powłoka

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

Obsługiwane opcje

Flaga	Znaczenie
`-F`, `--fixed-strings`	Wyszukiwanie stałego ciągu
`-i`, `--ignore-case`	Wyszukiwanie bez rozróżniania wielkości liter
`-w`, `--word-regexp`	Wyszukiwanie całych słów
`-v`, `--invert-match`	Odwrócenie dopasowań
`-c`, `--count`	Zliczanie pasujących wierszy
`-l`, `--files-with-matches`	Wyświetlanie pasujących plików
`--files-without-match`	Wyświetlanie niepasujących plików
`-I`, `--no-filename`	Ukrywanie prefiksów nazw plików
`-H`, `--with-filename`	Zawsze wyświetlanie prefiksów nazw plików
`-n`, `--line-number`	Wyświetlanie numerów wierszy
`-A N`, `--after-context N`	Wyświetlanie N wierszy po każdym dopasowaniu
`-B N`, `--before-context N`	Wyświetlanie N wierszy przed każdym dopasowaniem
`-C N`, `--context N`	Wyświetlanie N wierszy przed każdym dopasowaniem i po nim
`-m N`, `--max-count N`	Zatrzymanie po N dopasowaniach w każdym pliku
`-j N`, `--threads N`	Użycie N równoległych procesów roboczych
`-e P`, `--regexp P`	Wzorzec wyszukiwania
`-L`, `--follow`	Podążanie za dowiązaniami symbolicznymi
`--glob GLOB`	Uwzględnianie tylko plików, których ścieżki pasują do GLOB
`--type NAME`	Uwzględnianie typu pliku
`--type-not NAME`	Wykluczanie typu pliku
`--json`	Emitowanie zdarzeń ripgrep w stylu JSON
`--no-ignore`	Ignorowanie reguł `.gitignore` i `.grephignore`
`--hidden`	Uwzględnianie ukrytych plików
`--files`	Wyświetlanie plików kandydujących zamiast wyszukiwania
`--help`	Wyświetlanie wbudowanej pomocy

`sg`

Warstwa zgodności w stylu ast-grep. Obsługuje najczęściej używane flagi ast-grep. Zweryfikowany zakres opisano w macierzy funkcji.

Powłoka

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

run to kanoniczne polecenie ast-grep. scan i rewrite to aliasy dostępne wyłącznie w warstwie zgodności, odzwierciedlające typowe użycie. Działa też samo wywołanie (sg --pattern ... .), które uruchamia jednorazowe wyszukiwanie.

Przykłady

Powłoka

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

Obsługiwane opcje

Flaga	Znaczenie
`-p`, `--pattern PATTERN`	Wzorzec AST
`-r`, `--rewrite TEMPLATE`	Szablon przepisywania
`-l`, `--lang NAME`	Język AST. Domyślnie: `php`
`-j`, `--threads N`	Użycie N równoległych procesów roboczych
`-i`, `--interactive`	Potwierdzanie każdego przepisania
`-U`, `--update-all`	Zastosowanie przepisań bez potwierdzenia
`--files-with-matches`	Wyświetlanie tylko ścieżek plików z dopasowaniami
`--json[=STYLE]`	Emitowanie danych wyjściowych JSON. STYLE = `pretty`, `stream` lub `compact`
`--no-ignore [MODE]`	Ignorowanie reguł ignorowania repozytorium
`--hidden`	Uwzględnianie ukrytych plików
`--glob GLOB`, `--globs GLOB`	Uwzględnianie tylko plików, których ścieżki pasują do GLOB
`--type NAME`	Uwzględnianie typu pliku
`--type-not NAME`	Wykluczanie typu pliku
`--dry-run`	Podgląd przepisań bez zapisywania plików
`--help`	Wyświetlanie wbudowanej pomocy

Kody wyjścia

Greph stosuje konwencje grep / ripgrep:

Kod	Znaczenie
`0`	Znaleziono co najmniej jedno dopasowanie (lub w przypadku przepisywania zmieniono co najmniej jeden plik)
`1`	Nie znaleziono dopasowań
`2`	Błąd użycia lub błąd w czasie działania (nieprawidłowe argumenty, brak indeksu, błąd parsowania w trybie `--strict-parse`)