Reference CLI

Zobrazit jako Markdown Upravit na GitHub Dokumentace na d105217

Greph obsahuje čtyři spustitelné soubory. Všechny čtyři používají stejný engine; liší se rozhraním, které zpřístupňují.

Binární soubor	Účel
`greph`	Nativní textové vyhledávání, vyhledávání v AST a přepis AST
`greph-index`	Předehřátý textový index, index faktů AST a vyhledávání v AST s mezipamětí
`rg`	Wrapper kompatibilní se stylem ripgrep
`sg`	Wrapper kompatibilní se stylem ast-grep

Všechny cesty v příkladech používají ./vendor/bin/<binary>, který funguje s Greph 0.2.3 nainstalovanou jako závislost nebo novější verzí. Pokud pracujete s klonem repozitáře, nahraďte ji za ./bin/<binary>.

`greph`

Nativní textové vyhledávání, vyhledávání v AST a přepis AST.

Shell

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

Pokud cestu vynecháte, prohledá se aktuální adresář.

Textový režim

Výchozí režim. Vzory jsou regulární výrazy PCRE2, pokud není nastaveno -F.

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

Formát výstupu odpovídá grep -rn:

Text

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

Režim AST

Aktivuje se pomocí -p. Vzory se zapisují jako běžné PHP s metaproměnnými $VAR a $$$VARIADIC. Úplnou gramatiku vzorů najdete v části Režimy / Vyhledávání v AST.

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

Režim přepisu

Aktivuje se kombinací -p a -r. Šablona náhrady používá stejné metaproměnné jako vyhledávací vzor; zachycené uzly se vkládají podle názvu.

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

Možnosti

Příznak	Význam
`-F`	Vyhledávání pevného řetězce (bez regulárních výrazů)
`-i`	Porovnávání bez rozlišování velikosti písmen
`-w`	Porovnávání celých slov
`-v`	Obrátit výběr shod
`-c`	Počítat shody v jednotlivých souborech
`-l`	Vypsat pouze cesty k souborům se shodami
`-L`	Vypsat pouze cesty k souborům bez shod
`-h`	V textovém režimu potlačit předpony s názvy souborů
`-H`	V textovém režimu vždy vypisovat předpony s názvy souborů
`-n`	Zobrazit čísla řádků (výchozí: zapnuto)
`-A N`	Zobrazit N řádků za každou shodou
`-B N`	Zobrazit N řádků před každou shodou
`-C N`	Zobrazit N okolních řádků před každou shodou i za ní
`-m N`	Zastavit po N shodách v každém souboru
`-j N`	Použít N paralelních pracovníků
`-p PATTERN`	Vyhledávací vzor AST
`-r TEMPLATE`	Šablona přepisu AST (vyžaduje `-p`)
`--glob GLOB`	Zahrnout pouze soubory, jejichž cesty odpovídají GLOB
`--type NAME`	Zahrnout alias typu souboru (`php`, `js`, `md`, ...)
`--type-not NAME`	Vyloučit alias typu souboru
`--lang NAME`	Jazyk AST. Výchozí: `php`
`--json`	Vydat výstup JSON
`--no-ignore`	Ignorovat pravidla `.gitignore` a `.grephignore`
`--hidden`	Zahrnout skryté soubory
`--dry-run`	Zobrazit přepisy bez zápisu do souborů
`--interactive`	Potvrdit přepis každého souboru
`--help`	Zobrazit stručný návod k použití

`greph-index`

Předehřátý textový index, index faktů AST a vyhledávání v AST s mezipamětí.

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

Textový index

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

Textový index je předehřáté úložiště trigramů a výskytů identifikátorů. Ve výchozím nastavení se nachází v .greph-index/ v kořenovém adresáři indexu.

Sady indexů

Sady indexů převádějí opakované pracovní postupy s více indexy na pojmenovaný manifest:

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

Výchozí soubor manifestu je .greph-index-set.json. Každá položka odkazuje na kořenový adresář, režim a profil životního cyklu. set build a set refresh pracují s povolenými položkami; set search prohledá vybrané položky a odstraní duplicitní překrývající se shody.

Index faktů AST

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

Index faktů AST získává fakta na úrovni uzlů (volání, vytváření instancí, třídy, metody) a ukládá je do úložiště, ve kterém lze vyhledávat. Vyhledávání nejprve provede O(log n) nad klíčem faktu a pak výsledek ověří proti zdrojovému kódu. Ve výchozím nastavení je uložen v .greph-ast-index/.

Mezipaměť AST

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

Mezipaměť AST ukládá analyzované stromy na disk, aby se při vyhledávání nemusel spouštět analyzátor. Ve výchozím nastavení je uložena v .greph-ast-cache/.

Možnosti

Možnosti textového vyhledávání odpovídají sadě příznaků greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Další příznaky:

Příznak	Význam
`--index-dir DIR`	Použít nepředvolený adresář předehřátého indexu. Lze opakovat pro vyhledávání a statistiky ve více indexech.
`--lifecycle PROFILE`	Zásada sestavení: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Prahový počet souborů pro příležitostnou aktualizaci
`--auto-refresh-max-bytes N`	Prahová velikost v bajtech pro příležitostnou aktualizaci
`--manifest FILE`	Načíst manifest sady indexů. Výchozí: `.greph-index-set.json`
`--mode MODE`	Omezit operace se sadou na `text`, `ast-index` nebo `ast-cache`
`--index NAME`	Omezit operace se sadou na pojmenovanou položku manifestu. Lze opakovat.
`--show-index-origin`	Přidat před výstup vyhledávání ve více indexech nebo sadách název odpovídající položky indexu
`--trace-plan`	Vydat diagnostiku předehřátého plánovače do `stderr`
`--dry-refresh`	V `stats` oznámit, co by předehřáté vyhledávání provedlo, aniž by se cokoli měnilo
`--lang NAME`	Jazyk AST pro vyhledávání `ast-index` / `ast-cache`. Výchozí: `php`
`-j N`, `--jobs N`	Pracovníci pro prohledávání AST
`-l`, `--files-with-matches`	Vypsat pouze cesty k souborům se shodami (režim AST)
`--strict-parse`	Při chybách analýzy skončit chybou místo přeskočení
`--fallback MODE`	Chování při chybějícím indexu: `fail` (výchozí) nebo `scan`
`--help`	Zobrazit stručný návod k použití

`rg`

Wrapper kompatibilní se stylem ripgrep. Podporuje nejčastěji používané příznaky ripgrep. Ověřené možnosti jsou uvedeny v matici funkcí.

Shell

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

Příklady

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

Podporované možnosti

Příznak	Význam
`-F`, `--fixed-strings`	Vyhledávání pevného řetězce
`-i`, `--ignore-case`	Vyhledávání bez rozlišování velikosti písmen
`-w`, `--word-regexp`	Vyhledávání celých slov
`-v`, `--invert-match`	Obrátit výběr shod
`-c`, `--count`	Počítat řádky se shodami
`-l`, `--files-with-matches`	Vypsat soubory se shodami
`--files-without-match`	Vypsat soubory bez shod
`-I`, `--no-filename`	Potlačit předpony s názvy souborů
`-H`, `--with-filename`	Vždy vypisovat předpony s názvy souborů
`-n`, `--line-number`	Zobrazit čísla řádků
`-A N`, `--after-context N`	Zobrazit N řádků za každou shodou
`-B N`, `--before-context N`	Zobrazit N řádků před každou shodou
`-C N`, `--context N`	Zobrazit N řádků před každou shodou i za ní
`-m N`, `--max-count N`	Zastavit po N shodách v každém souboru
`-j N`, `--threads N`	Použít N paralelních pracovníků
`-e P`, `--regexp P`	Vyhledávací vzor
`-L`, `--follow`	Sledovat symbolické odkazy
`--glob GLOB`	Zahrnout pouze soubory, jejichž cesty odpovídají GLOB
`--type NAME`	Zahrnout typ souboru
`--type-not NAME`	Vyloučit typ souboru
`--json`	Vydat události ripgrep ve stylu JSON
`--no-ignore`	Ignorovat pravidla `.gitignore` a `.grephignore`
`--hidden`	Zahrnout skryté soubory
`--files`	Vypsat kandidátní soubory místo vyhledávání
`--help`	Zobrazit stručný návod k použití

`sg`

Wrapper kompatibilní se stylem ast-grep. Podporuje nejčastěji používané příznaky ast-grep. Ověřené možnosti jsou uvedeny v matici funkcí.

Shell

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

run je kanonický příkaz ast-grep. scan a rewrite jsou pouze aliasy wrapperu, které odpovídají běžnému použití. Funguje i samotné spuštění (sg --pattern ... .) jako jednorázové vyhledávání.

Příklady

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

Podporované možnosti

Příznak	Význam
`-p`, `--pattern PATTERN`	Vzor AST
`-r`, `--rewrite TEMPLATE`	Šablona přepisu
`-l`, `--lang NAME`	Jazyk AST. Výchozí: `php`
`-j`, `--threads N`	Použít N paralelních pracovníků
`-i`, `--interactive`	Potvrdit každý přepis
`-U`, `--update-all`	Provést přepisy bez potvrzení
`--files-with-matches`	Vypsat pouze cesty k souborům se shodami
`--json[=STYLE]`	Vydat výstup JSON. STYLE = `pretty`, `stream` nebo `compact`
`--no-ignore [MODE]`	Ignorovat pravidla ignorování repozitáře
`--hidden`	Zahrnout skryté soubory
`--glob GLOB`, `--globs GLOB`	Zahrnout pouze soubory, jejichž cesty odpovídají GLOB
`--type NAME`	Zahrnout typ souboru
`--type-not NAME`	Vyloučit typ souboru
`--dry-run`	Zobrazit náhled přepisů bez zápisu do souborů
`--help`	Zobrazit stručný návod k použití

Návratové kódy

Greph dodržuje konvence grep / ripgrep:

Kód	Význam
`0`	Byla nalezena alespoň jedna shoda (nebo se v případě přepisů změnil alespoň jeden soubor)
`1`	Nebyly nalezeny žádné shody
`2`	Chyba použití nebo běhu (chybné argumenty, chybějící index, chyba analýzy v režimu `--strict-parse`)