Referencia de CLI

Ver como Markdown Editar en GitHub Documentación de d105217

Greph incluye cuatro ejecutables. Los cuatro comparten el mismo motor; se diferencian en la interfaz que ofrecen.

Binario	Propósito
`greph`	Búsqueda de texto nativa, búsqueda AST y reescritura AST
`greph-index`	Índice de texto precargado, índice de hechos AST y búsqueda AST en caché
`rg`	Envoltorio de compatibilidad al estilo de ripgrep
`sg`	Envoltorio de compatibilidad al estilo de ast-grep

Todas las rutas de los ejemplos usan ./vendor/bin/<binary>, que funciona con Greph 0.2.3 o versiones posteriores instaladas como dependencia. Sustituya ./bin/<binary> si trabaja desde un clon del repositorio.

`greph`

Búsqueda de texto nativa, búsqueda AST y reescritura AST.

Shell

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

Si se omite una ruta, se busca en el directorio actual.

Modo de texto

Modo predeterminado. Los patrones son expresiones regulares PCRE2, salvo que se establezca -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

El formato de salida coincide con el de grep -rn:

Text

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

Modo AST

Se activa con -p. Los patrones se escriben como PHP normales, con met variables $VAR y $$$VARIADIC. Consulte Modos / Búsqueda AST para ver la gramática completa de los patrones.

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

Modo de reescritura

Se activa al combinar -p con -r. La plantilla de reemplazo usa los mismos met variables que el patrón de búsqueda; los nodos capturados se insertan por nombre.

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

Opciones

Opción	Significado
`-F`	Búsqueda de cadenas literales (sin expresiones regulares)
`-i`	Coincidencia sin distinguir mayúsculas y minúsculas
`-w`	Coincidencia de palabras completas
`-v`	Invertir coincidencia
`-c`	Contar coincidencias por archivo
`-l`	Mostrar solo las rutas de archivos con coincidencias
`-L`	Mostrar solo las rutas de archivos sin coincidencias
`-h`	Suprimir prefijos de nombre de archivo en modo de texto
`-H`	Mostrar siempre prefijos de nombre de archivo en modo de texto
`-n`	Mostrar números de línea (activado de forma predeterminada)
`-A N`	Mostrar N líneas después de cada coincidencia
`-B N`	Mostrar N líneas antes de cada coincidencia
`-C N`	Mostrar N líneas de contexto antes y después de cada coincidencia
`-m N`	Detenerse tras N coincidencias por archivo
`-j N`	Usar N procesos de trabajo en paralelo
`-p PATTERN`	Patrón de búsqueda AST
`-r TEMPLATE`	Plantilla de reescritura AST (requiere `-p`)
`--glob GLOB`	Incluir solo archivos cuyas rutas coincidan con GLOB
`--type NAME`	Incluir un alias de tipo de archivo (`php`, `js`, `md`, ...)
`--type-not NAME`	Excluir un alias de tipo de archivo
`--lang NAME`	Lenguaje AST. Predeterminado: `php`
`--json`	Emitir salida JSON
`--no-ignore`	Ignorar las reglas de `.gitignore` y `.grephignore`
`--hidden`	Incluir archivos ocultos
`--dry-run`	Mostrar reescrituras sin escribir los archivos
`--interactive`	Confirmar cada archivo reescrito
`--help`	Mostrar ayuda de uso integrada

`greph-index`

Índice de texto precargado, índice de hechos AST y búsqueda AST en caché.

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

Índice de texto

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

El índice de texto es un almacén precargado de trigramas y publicaciones de identificadores. De forma predeterminada, se encuentra en .greph-index/ dentro de la raíz indexada.

Conjuntos de índices

Los conjuntos de índices convierten los flujos de trabajo repetidos con varios índices en un manifiesto con nombre:

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

El archivo de manifiesto predeterminado es .greph-index-set.json. Cada entrada apunta a una raíz, un modo y un perfil de ciclo de vida. set build y set refresh operan sobre las entradas habilitadas; set search se ejecuta en las entradas seleccionadas y elimina las coincidencias duplicadas.

Índice de hechos 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

El índice de hechos AST extrae datos a nivel de nodo (llamadas, instanciaciones, clases y métodos) y los guarda en un almacén consultable. Las búsquedas usan O(log n) sobre la clave del hecho y luego se verifican con el código fuente. De forma predeterminada, se guarda en .greph-ast-index/.

Caché 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 caché AST guarda los árboles analizados en el disco para que las búsquedas omitan por completo el analizador. De forma predeterminada, se guarda en .greph-ast-cache/.

Opciones

Las opciones de búsqueda de texto coinciden con el conjunto de opciones greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Opciones adicionales:

Opción	Significado
`--index-dir DIR`	Usar un directorio de índice precargado distinto del predeterminado. Repetible para búsquedas y estadísticas con varios índices.
`--lifecycle PROFILE`	Política de creación: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Umbral de archivos para la actualización oportunista
`--auto-refresh-max-bytes N`	Umbral de bytes para la actualización oportunista
`--manifest FILE`	Cargar un manifiesto de conjunto de índices. Predeterminado: `.greph-index-set.json`
`--mode MODE`	Limitar las operaciones del conjunto a `text`, `ast-index` o `ast-cache`
`--index NAME`	Limitar las operaciones del conjunto a una entrada de manifiesto con nombre. Repetible.
`--show-index-origin`	Anteponer a la salida de búsquedas precargadas con varios índices o conjuntos el nombre de la entrada de índice correspondiente
`--trace-plan`	Emitir diagnósticos del planificador precargado en `stderr`
`--dry-refresh`	En `stats`, informar de lo que haría una búsqueda precargada sin modificar nada
`--lang NAME`	Lenguaje AST para búsquedas `ast-index` / `ast-cache`. Predeterminado: `php`
`-j N`, `--jobs N`	Procesos de trabajo para análisis AST
`-l`, `--files-with-matches`	Mostrar solo las rutas de archivos con coincidencias (modo AST)
`--strict-parse`	Fallar ante errores de análisis en vez de omitirlos
`--fallback MODE`	Comportamiento cuando falta el índice: `fail` (predeterminado) o `scan`
`--help`	Mostrar ayuda de uso integrada

`rg`

Envoltorio de compatibilidad al estilo de ripgrep. Admite las opciones ripgrep más utilizadas. La compatibilidad verificada se publica en la matriz de funciones.

Shell

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

Ejemplos

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

Opciones admitidas

Opción	Significado
`-F`, `--fixed-strings`	Búsqueda de cadenas literales
`-i`, `--ignore-case`	Búsqueda sin distinguir mayúsculas y minúsculas
`-w`, `--word-regexp`	Búsqueda de palabras completas
`-v`, `--invert-match`	Invertir coincidencias
`-c`, `--count`	Contar líneas coincidentes
`-l`, `--files-with-matches`	Mostrar archivos con coincidencias
`--files-without-match`	Mostrar archivos sin coincidencias
`-I`, `--no-filename`	Suprimir prefijos de nombre de archivo
`-H`, `--with-filename`	Mostrar siempre prefijos de nombre de archivo
`-n`, `--line-number`	Mostrar números de línea
`-A N`, `--after-context N`	Mostrar N líneas después de cada coincidencia
`-B N`, `--before-context N`	Mostrar N líneas antes de cada coincidencia
`-C N`, `--context N`	Mostrar N líneas antes y después de cada coincidencia
`-m N`, `--max-count N`	Detenerse tras N coincidencias por archivo
`-j N`, `--threads N`	Usar N procesos de trabajo en paralelo
`-e P`, `--regexp P`	Patrón de búsqueda
`-L`, `--follow`	Seguir enlaces simbólicos
`--glob GLOB`	Incluir solo archivos cuyas rutas coincidan con GLOB
`--type NAME`	Incluir un tipo de archivo
`--type-not NAME`	Excluir un tipo de archivo
`--json`	Emitir eventos ripgrep JSON
`--no-ignore`	Ignorar las reglas de `.gitignore` y `.grephignore`
`--hidden`	Incluir archivos ocultos
`--files`	Mostrar los archivos candidatos en lugar de buscarlos
`--help`	Mostrar ayuda de uso integrada

`sg`

Envoltorio de compatibilidad al estilo de ast-grep. Admite las opciones ast-grep más utilizadas. La compatibilidad verificada se publica en la matriz de funciones.

Shell

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

run es el verbo canónico de ast-grep. scan y rewrite son alias exclusivos del envoltorio que reflejan el uso habitual. También funciona una invocación sin argumentos (sg --pattern ... .) para realizar una búsqueda puntual.

Ejemplos

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

Opciones admitidas

Opción	Significado
`-p`, `--pattern PATTERN`	Patrón AST
`-r`, `--rewrite TEMPLATE`	Plantilla de reescritura
`-l`, `--lang NAME`	Lenguaje AST. Predeterminado: `php`
`-j`, `--threads N`	Usar N procesos de trabajo en paralelo
`-i`, `--interactive`	Confirmar cada reescritura
`-U`, `--update-all`	Aplicar reescrituras sin confirmación
`--files-with-matches`	Mostrar solo las rutas de archivos con coincidencias
`--json[=STYLE]`	Emitir salida JSON. STYLE = `pretty`, `stream` o `compact`
`--no-ignore [MODE]`	Ignorar las reglas de exclusión del repositorio
`--hidden`	Incluir archivos ocultos
`--glob GLOB`, `--globs GLOB`	Incluir solo archivos cuyas rutas coincidan con GLOB
`--type NAME`	Incluir un tipo de archivo
`--type-not NAME`	Excluir un tipo de archivo
`--dry-run`	Previsualizar reescrituras sin escribir los archivos
`--help`	Mostrar ayuda de uso integrada

Códigos de salida

Greph sigue las convenciones de grep / ripgrep:

Código	Significado
`0`	Se encontró al menos una coincidencia (o, en las reescrituras, se modificó al menos un archivo)
`1`	No se encontraron coincidencias
`2`	Error de uso o fallo en tiempo de ejecución (argumentos incorrectos, falta el índice, error de análisis en el modo `--strict-parse`)