Référence CLI

Afficher au format Markdown Modifier sur GitHub Documentation de d105217

Greph fournit quatre exécutables. Ils partagent tous le même moteur ; seule leur interface diffère.

Binaire	Fonction
`greph`	Recherche textuelle native, recherche AST et réécriture AST
`greph-index`	Index textuel préchauffé, index de faits AST et recherche AST mise en cache
`rg`	Enveloppe de compatibilité de type ripgrep
`sg`	Enveloppe de compatibilité de type ast-grep

Tous les chemins des exemples utilisent ./vendor/bin/<binary>, qui fonctionne avec Greph 0.2.3 ou une version ultérieure installée comme dépendance. Remplacez-le par ./bin/<binary> si vous travaillez à partir d’un clone du dépôt.

`greph`

Recherche textuelle native, recherche AST et réécriture AST.

Shell

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

Si le chemin est omis, la recherche porte sur le répertoire courant.

Mode texte

Mode par défaut. Les motifs sont des expressions régulières PCRE2, sauf si -F est défini.

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

Le format de sortie correspond à grep -rn :

Text

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

Mode AST

Activé par -p. Les motifs sont écrits comme du PHP ordinaire avec des métavariables $VAR et $$$VARIADIC. Consultez Modes / Recherche AST pour connaître la grammaire complète des motifs.

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

Mode réécriture

Activé en combinant -p et -r. Le modèle de remplacement utilise les mêmes métavariables que le motif de recherche ; les nœuds capturés sont insérés par nom.

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

Options

Option	Signification
`-F`	Recherche de chaînes exactes (sans expression régulière)
`-i`	Recherche sans distinction entre majuscules et minuscules
`-w`	Correspondance sur des mots entiers
`-v`	Inverser la correspondance
`-c`	Compter les correspondances par fichier
`-l`	Lister uniquement les chemins des fichiers correspondants
`-L`	Lister uniquement les chemins des fichiers sans correspondance
`-h`	Supprimer les préfixes de nom de fichier en mode texte
`-H`	Toujours afficher les préfixes de nom de fichier en mode texte
`-n`	Afficher les numéros de ligne (par défaut : activé)
`-A N`	Afficher N lignes après chaque correspondance
`-B N`	Afficher N lignes avant chaque correspondance
`-C N`	Afficher N lignes de contexte avant et après chaque correspondance
`-m N`	Arrêter après N correspondances par fichier
`-j N`	Utiliser N processus de travail en parallèle
`-p PATTERN`	Motif de recherche AST
`-r TEMPLATE`	Modèle de réécriture AST (nécessite `-p`)
`--glob GLOB`	Inclure uniquement les fichiers dont le chemin correspond à GLOB
`--type NAME`	Inclure un alias de type de fichier (`php`, `js`, `md`, ...)
`--type-not NAME`	Exclure un alias de type de fichier
`--lang NAME`	Langage AST. Par défaut : `php`
`--json`	Émettre une sortie JSON
`--no-ignore`	Ignorer les règles `.gitignore` et `.grephignore`
`--hidden`	Inclure les fichiers masqués
`--dry-run`	Afficher les réécritures sans modifier les fichiers
`--interactive`	Confirmer chaque fichier réécrit
`--help`	Afficher l’aide en ligne

`greph-index`

Index textuel préchauffé, index de faits AST et recherche AST mise en 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...]

Index textuel

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’index textuel est un stockage préchauffé de trigrammes et de listes de références d’identifiants. Par défaut, il se trouve dans .greph-index/ à la racine indexée.

Ensembles d’index

Les ensembles d’index regroupent les flux de travail répétés sur plusieurs index dans un manifeste nommé :

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

Le fichier manifeste par défaut est .greph-index-set.json. Chaque entrée indique une racine, un mode et un profil de cycle de vie. set build et set refresh opèrent sur les entrées activées ; set search répartit la recherche sur les entrées sélectionnées et élimine les correspondances en double.

Index de faits 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’index de faits AST extrait les faits au niveau des nœuds (appels, instanciations, classes, méthodes) dans un stockage interrogeable. Les recherches se font en O(log n) sur la clé de fait, puis sont vérifiées par rapport au code source. Par défaut, il est stocké dans .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

Le cache AST stocke les arbres analysés sur disque afin que les recherches ignorent complètement l’analyseur. Par défaut, il est stocké dans .greph-ast-cache/.

Options

Les options de recherche textuelle correspondent à l’ensemble d’options greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Options supplémentaires :

Option	Signification
`--index-dir DIR`	Utiliser un répertoire d’index préchauffé autre que celui par défaut. Répétable pour la recherche et les statistiques sur plusieurs index.
`--lifecycle PROFILE`	Politique de construction : `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Seuil de fichiers pour l’actualisation opportuniste
`--auto-refresh-max-bytes N`	Seuil d’octets pour l’actualisation opportuniste
`--manifest FILE`	Charger un manifeste d’ensemble d’index. Par défaut : `.greph-index-set.json`
`--mode MODE`	Limiter les opérations sur l’ensemble à `text`, `ast-index` ou `ast-cache`
`--index NAME`	Limiter les opérations sur l’ensemble à une entrée de manifeste nommée. Répétable.
`--show-index-origin`	Préfixer la sortie de recherche ou d’ensemble sur plusieurs index préchauffés par le nom de l’entrée d’index correspondante
`--trace-plan`	Émettre les diagnostics du planificateur préchauffé vers `stderr`
`--dry-refresh`	En `stats`, indiquer ce qu’effectuerait une recherche préchauffée sans rien modifier
`--lang NAME`	Langage AST pour les recherches `ast-index` / `ast-cache`. Par défaut : `php`
`-j N`, `--jobs N`	Processus de travail pour les analyses AST
`-l`, `--files-with-matches`	Lister uniquement les chemins des fichiers correspondants (mode AST)
`--strict-parse`	Échouer en cas d’erreur d’analyse au lieu de l’ignorer
`--fallback MODE`	Comportement en l’absence d’index : `fail` (par défaut) ou `scan`
`--help`	Afficher l’aide en ligne

`rg`

Enveloppe de compatibilité de type ripgrep. Prend en charge les options ripgrep les plus couramment utilisées. Les fonctionnalités vérifiées sont publiées dans la matrice des fonctionnalités.

Shell

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

Exemples

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

Options prises en charge

Option	Signification
`-F`, `--fixed-strings`	Recherche de chaînes exactes
`-i`, `--ignore-case`	Recherche sans distinction entre majuscules et minuscules
`-w`, `--word-regexp`	Recherche de mots entiers
`-v`, `--invert-match`	Inverser les correspondances
`-c`, `--count`	Compter les lignes correspondantes
`-l`, `--files-with-matches`	Lister les fichiers correspondants
`--files-without-match`	Lister les fichiers sans correspondance
`-I`, `--no-filename`	Supprimer les préfixes de nom de fichier
`-H`, `--with-filename`	Toujours afficher les préfixes de nom de fichier
`-n`, `--line-number`	Afficher les numéros de ligne
`-A N`, `--after-context N`	Afficher N lignes après chaque correspondance
`-B N`, `--before-context N`	Afficher N lignes avant chaque correspondance
`-C N`, `--context N`	Afficher N lignes avant et après chaque correspondance
`-m N`, `--max-count N`	Arrêter après N correspondances par fichier
`-j N`, `--threads N`	Utiliser N processus de travail en parallèle
`-e P`, `--regexp P`	Motif de recherche
`-L`, `--follow`	Suivre les liens symboliques
`--glob GLOB`	Inclure uniquement les fichiers dont le chemin correspond à GLOB
`--type NAME`	Inclure un type de fichier
`--type-not NAME`	Exclure un type de fichier
`--json`	Émettre des événements ripgrep de type JSON
`--no-ignore`	Ignorer les règles `.gitignore` et `.grephignore`
`--hidden`	Inclure les fichiers masqués
`--files`	Lister les fichiers candidats au lieu d’effectuer une recherche
`--help`	Afficher l’aide en ligne

`sg`

Enveloppe de compatibilité de type ast-grep. Prend en charge les options ast-grep les plus couramment utilisées. Les fonctionnalités vérifiées sont publiées dans la matrice des fonctionnalités.

Shell

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

run est la commande canonique de type ast-grep. scan et rewrite sont des alias réservés à l’enveloppe, qui reprennent les usages courants. Un appel sans argument (sg --pattern ... .) lance également une recherche ponctuelle.

Exemples

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

Options prises en charge

Option	Signification
`-p`, `--pattern PATTERN`	Motif AST
`-r`, `--rewrite TEMPLATE`	Modèle de réécriture
`-l`, `--lang NAME`	Langage AST. Par défaut : `php`
`-j`, `--threads N`	Utiliser N processus de travail en parallèle
`-i`, `--interactive`	Confirmer chaque réécriture
`-U`, `--update-all`	Appliquer les réécritures sans confirmation
`--files-with-matches`	Afficher uniquement les chemins des fichiers contenant des correspondances
`--json[=STYLE]`	Émettre une sortie JSON. STYLE = `pretty`, `stream` ou `compact`
`--no-ignore [MODE]`	Ignorer les règles d’exclusion du dépôt
`--hidden`	Inclure les fichiers masqués
`--glob GLOB`, `--globs GLOB`	Inclure uniquement les fichiers dont le chemin correspond à GLOB
`--type NAME`	Inclure un type de fichier
`--type-not NAME`	Exclure un type de fichier
`--dry-run`	Prévisualiser les réécritures sans modifier les fichiers
`--help`	Afficher l’aide en ligne

Codes de sortie

Greph suit les conventions de grep / ripgrep :

Code	Signification
`0`	Au moins une correspondance a été trouvée (ou, pour les réécritures, au moins un fichier a été modifié)
`1`	Aucune correspondance trouvée
`2`	Erreur d’utilisation ou échec à l’exécution (arguments incorrects, index manquant, erreur d’analyse en mode `--strict-parse`)