Riferimento CLI

Visualizza come Markdown Modifica su GitHub Documentazione di d105217

Greph include quattro eseguibili. Tutti e quattro condividono lo stesso motore; cambia solo l'interfaccia che espongono.

Binario	Scopo
`greph`	Ricerca testuale nativa, ricerca AST e riscrittura AST
`greph-index`	Indice testuale riscaldato, indice di fatti AST e ricerca AST memorizzata nella cache
`rg`	Wrapper di compatibilità in stile ripgrep
`sg`	Wrapper di compatibilità in stile ast-grep

Tutti i percorsi negli esempi usano ./vendor/bin/<binary>, che funziona con Greph 0.2.3 o versioni successive installate come dipendenza. Sostituisci con ./bin/<binary> se stai lavorando da un clone del repository.

`greph`

Ricerca testuale nativa, ricerca AST e riscrittura AST.

Shell

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

Se si omette un percorso, la ricerca viene eseguita nella directory corrente.

Modalità testuale

Modalità predefinita. I pattern sono espressioni regolari PCRE2, a meno che non sia impostato -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

Il formato di output corrisponde a grep -rn:

Text

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

Modalità AST

Si attiva con -p. I pattern sono scritti come normale PHP con metavariabili $VAR e $$$VARIADIC. Per la grammatica completa dei pattern, consulta Modalità / Ricerca 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

Modalità di riscrittura

Si attiva combinando -p con -r. Il modello di sostituzione usa le stesse metavariabili del pattern di ricerca; i nodi acquisiti vengono inseriti usando il nome.

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

Opzioni

Opzione	Significato
`-F`	Ricerca per stringa esatta (senza espressioni regolari)
`-i`	Ricerca senza distinzione tra maiuscole e minuscole
`-w`	Corrispondenza di parole intere
`-v`	Inverti la corrispondenza
`-c`	Conta le corrispondenze per file
`-l`	Elenca solo i percorsi dei file corrispondenti
`-L`	Elenca solo i percorsi dei file non corrispondenti
`-h`	Sopprimi i prefissi dei nomi file in modalità testuale
`-H`	Stampa sempre i prefissi dei nomi file in modalità testuale
`-n`	Mostra i numeri di riga (predefinito: attivo)
`-A N`	Mostra N righe dopo ogni corrispondenza
`-B N`	Mostra N righe prima di ogni corrispondenza
`-C N`	Mostra N righe di contesto prima e dopo ogni corrispondenza
`-m N`	Interrompi dopo N corrispondenze per file
`-j N`	Usa N worker paralleli
`-p PATTERN`	Pattern di ricerca AST
`-r TEMPLATE`	Modello di riscrittura AST (richiede `-p`)
`--glob GLOB`	Includi solo i file il cui percorso corrisponde a GLOB
`--type NAME`	Includi un alias di tipo file (`php`, `js`, `md`, ...)
`--type-not NAME`	Escludi un alias di tipo file
`--lang NAME`	Linguaggio AST. Predefinito: `php`
`--json`	Genera output JSON
`--no-ignore`	Ignora le regole `.gitignore` e `.grephignore`
`--hidden`	Includi i file nascosti
`--dry-run`	Mostra le riscritture senza scrivere i file
`--interactive`	Conferma ogni file riscritto
`--help`	Mostra la guida rapida inline

`greph-index`

Indice testuale riscaldato, indice di fatti AST e ricerca AST memorizzata nella 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...]

Indice testuale

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

L'indice testuale è un archivio riscaldato di trigrammi e posting degli identificatori. Per impostazione predefinita si trova in .greph-index/ nella root indicizzata.

Set di indici

I set di indici trasformano i flussi di lavoro ripetuti con più indici in un manifest con nome:

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

Il file manifest predefinito è .greph-index-set.json. Ogni voce punta a una root, una modalità e un profilo del ciclo di vita. set build e set refresh operano sulle voci abilitate; set search si applica alle voci selezionate ed elimina le corrispondenze sovrapposte.

Indice di fatti 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

L'indice di fatti AST estrae fatti a livello di nodo (chiamate, istanziazioni, classi, metodi) in un archivio interrogabile. Le ricerche avvengono tramite O(log n) sulla chiave del fatto, quindi vengono verificate sul codice sorgente. Per impostazione predefinita, è archiviato in .greph-ast-index/.

Cache 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

La cache AST archivia gli alberi analizzati su disco, così le ricerche possono saltare del tutto il parser. Per impostazione predefinita, è archiviata in .greph-ast-cache/.

Opzioni

Le opzioni di ricerca testuale corrispondono al set di flag greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Flag aggiuntivi:

Opzione	Significato
`--index-dir DIR`	Usa una directory di indice riscaldato non predefinita. Ripetibile per ricerche e statistiche su più indici.
`--lifecycle PROFILE`	Criterio di compilazione: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Soglia dei file per l'aggiornamento opportunistico
`--auto-refresh-max-bytes N`	Soglia dei byte per l'aggiornamento opportunistico
`--manifest FILE`	Carica un manifest di set di indici. Predefinito: `.greph-index-set.json`
`--mode MODE`	Limita le operazioni sui set a `text`, `ast-index` o `ast-cache`
`--index NAME`	Limita le operazioni sui set a una voce del manifest specificata. Ripetibile.
`--show-index-origin`	Aggiunge ai risultati delle ricerche su più indici o sui set il nome della voce di indice corrispondente
`--trace-plan`	Invia la diagnostica del planner riscaldato a `stderr`
`--dry-refresh`	In `stats`, mostra cosa farebbe una ricerca riscaldata senza modificare nulla
`--lang NAME`	Linguaggio AST per le ricerche `ast-index` / `ast-cache`. Predefinito: `php`
`-j N`, `--jobs N`	Worker per le scansioni AST
`-l`, `--files-with-matches`	Elenca solo i percorsi dei file corrispondenti (modalità AST)
`--strict-parse`	Genera errori di analisi invece di ignorarli
`--fallback MODE`	Comportamento in assenza di indice: `fail` (predefinito) o `scan`
`--help`	Mostra la guida rapida inline

`rg`

Wrapper di compatibilità in stile ripgrep. Supporta i flag ripgrep più usati. Le funzionalità verificate sono elencate nella matrice delle funzionalità.

Shell

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

Esempi

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

Opzioni supportate

Opzione	Significato
`-F`, `--fixed-strings`	Ricerca per stringa esatta
`-i`, `--ignore-case`	Ricerca senza distinzione tra maiuscole e minuscole
`-w`, `--word-regexp`	Ricerca di parole intere
`-v`, `--invert-match`	Inverte le corrispondenze
`-c`, `--count`	Conta le righe corrispondenti
`-l`, `--files-with-matches`	Elenca i file corrispondenti
`--files-without-match`	Elenca i file non corrispondenti
`-I`, `--no-filename`	Sopprime i prefissi dei nomi file
`-H`, `--with-filename`	Stampa sempre i prefissi dei nomi file
`-n`, `--line-number`	Mostra i numeri di riga
`-A N`, `--after-context N`	Mostra N righe dopo ogni corrispondenza
`-B N`, `--before-context N`	Mostra N righe prima di ogni corrispondenza
`-C N`, `--context N`	Mostra N righe prima e dopo ogni corrispondenza
`-m N`, `--max-count N`	Interrompe dopo N corrispondenze per file
`-j N`, `--threads N`	Usa N worker paralleli
`-e P`, `--regexp P`	Pattern di ricerca
`-L`, `--follow`	Segue i collegamenti simbolici
`--glob GLOB`	Includi solo i file il cui percorso corrisponde a GLOB
`--type NAME`	Includi un tipo di file
`--type-not NAME`	Escludi un tipo di file
`--json`	Genera eventi ripgrep in stile JSON
`--no-ignore`	Ignora le regole `.gitignore` e `.grephignore`
`--hidden`	Includi i file nascosti
`--files`	Elenca i file candidati invece di eseguire la ricerca
`--help`	Mostra la guida rapida inline

`sg`

Wrapper di compatibilità in stile ast-grep. Supporta i flag ast-grep più usati. Le funzionalità verificate sono elencate nella matrice delle funzionalità.

Shell

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

run è il verbo canonico di ast-grep. scan e rewrite sono alias disponibili solo nei wrapper, che riproducono l'uso comune. Funziona anche un'invocazione senza argomenti (sg --pattern ... .) per una ricerca singola.

Esempi

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

Opzioni supportate

Opzione	Significato
`-p`, `--pattern PATTERN`	Pattern AST
`-r`, `--rewrite TEMPLATE`	Modello di riscrittura
`-l`, `--lang NAME`	Linguaggio AST. Predefinito: `php`
`-j`, `--threads N`	Usa N worker paralleli
`-i`, `--interactive`	Conferma ogni riscrittura
`-U`, `--update-all`	Applica le riscritture senza conferma
`--files-with-matches`	Stampa solo i percorsi dei file con corrispondenze
`--json[=STYLE]`	Genera output JSON. STILE = `pretty`, `stream` o `compact`
`--no-ignore [MODE]`	Ignora le regole di esclusione del repository
`--hidden`	Includi i file nascosti
`--glob GLOB`, `--globs GLOB`	Includi solo i file il cui percorso corrisponde a GLOB
`--type NAME`	Includi un tipo di file
`--type-not NAME`	Escludi un tipo di file
`--dry-run`	Anteprima delle riscritture senza scrivere i file
`--help`	Mostra la guida rapida inline

Codici di uscita

Greph segue le convenzioni di grep / ripgrep:

Codice	Significato
`0`	È stata trovata almeno una corrispondenza (oppure, per le riscritture, è stato modificato almeno un file)
`1`	Nessuna corrispondenza trovata
`2`	Errore di utilizzo o di esecuzione (argomenti non validi, indice mancante, errore di analisi in modalità `--strict-parse`)