# Compatibilidad con rg

`vendor/bin/rg` es un envoltorio de compatibilidad al estilo de ripgrep. Acepta las opciones ripgrep más utilizadas, recorre el árbol de archivos igual que ripgrep y genera resultados coincidentes. La interfaz verificada se reproduce a partir de pruebas de sondeo con el binario original de `rg` y se encuentra en [Avanzado / Matriz de funciones](https://greph.inline0.dev/es/docs/advanced/feature-matrix).

El envoltorio es un traductor ligero de CLI; la búsqueda real la realiza el mismo motor `Greph\Text\TextSearcher` que usa `vendor/bin/greph`.

## Cuándo usarlo

Use el envoltorio cuando:

- Ya tenga una herramienta, un agente o un script que invoque `rg`.
- Quiera un reemplazo directo que funcione en entornos donde no pueda instalar ripgrep (alojamiento compartido, contenedores reforzados, PaaS restringidas).
- Quiera la facilidad de uso de ripgrep en una infraestructura que solo tenga PHP.

Use `vendor/bin/greph` de forma nativa cuando:

- Escriba código nuevo y no necesite la interfaz de ripgrep CLI.
- Quiera acceder a opciones nativas que el envoltorio no ofrece (por ejemplo, el modo AST).

## Uso

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

Una invocación sin argumentos busca de forma recursiva en `.`:

```bash
./vendor/bin/rg -F "function"
```

`--files` muestra los archivos candidatos en lugar de buscarlos:

```bash
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden
```

## Salida de JSON

`--json` genera la misma carga útil con formato de eventos que produce ripgrep:

```bash
./vendor/bin/rg --json -F "function walk" src/Greph.php
```

```json
{"type":"begin","data":{"path":{"text":"src/Greph.php"}}}
{"type":"match","data":{"path":{"text":"src/Greph.php"},"lines":{"text":"    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList\n"},"line_number":41,"absolute_offset":1034,"submatches":[{"match":{"text":"function walk"},"start":18,"end":31}]}}
{"type":"end","data":{"path":{"text":"src/Greph.php"},"binary_offset":null,"stats":{"elapsed":{"secs":0,"nanos":0,"human":"0.000000s"},"searches":1,"searches_with_match":1,"bytes_searched":13383,"bytes_printed":282,"matched_lines":1,"matches":1}}}
{"type":"summary","data":{"elapsed_total":{"human":"0.000000s","nanos":0,"secs":0},"stats":{"bytes_printed":282,"bytes_searched":13383,"matched_lines":1,"matches":1,"searches":1,"searches_with_match":1,"elapsed":{"human":"0.000000s","nanos":0,"secs":0}}}}
```

Los tiempos de los objetos `stats` siempre se indican como cero.

Este es el esquema que esperan las herramientas posteriores cuando habilitan la salida estructurada de ripgrep. Si quiere un formato más sencillo, use `vendor/bin/greph --json`.

## Interfaz verificada

Las siguientes opciones se han verificado con el propio `rg` en la [matriz de funciones](https://greph.inline0.dev/es/docs/advanced/feature-matrix). El binario original y el envoltorio generan resultados equivalentes para cada prueba. Si una opción tiene una forma corta y otra larga, la prueba usa una de ellas y el envoltorio interpreta ambas como la misma opción.

### Opciones de búsqueda

- `-F`, `--fixed-strings`
- `-i`, `--ignore-case`
- `-w`, `--word-regexp`
- `-v`, `--invert-match`
- `-c`, `--count`
- `-l`, `--files-with-matches`
- `--files-without-match`
- `-I`, `--no-filename`
- `-H`, `--with-filename`
- `-n`, `--line-number`
- `-A N`, `--after-context N`
- `-B N`, `--before-context N`
- `-C N`, `--context N`
- `-m N`, `--max-count N`
- `-e P`, `--regexp P`

### Opciones del recorrido

- `-L`, `--follow`
- `--glob GLOB`
- `--type NAME`
- `--type-not NAME`
- `--no-ignore`
- `--hidden`
- `--files`
- `--files --hidden`
- `--files --type NAME`

### Opciones de salida

- `--json`

### Aceptadas sin una prueba

El envoltorio también acepta estas opciones, pero todavía no hay pruebas de la matriz de funciones que las cubran:

- `-j N`, `--threads N` (número de procesos de trabajo; consulte [Procesos de trabajo en paralelo](https://greph.inline0.dev/es/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Limitaciones

El envoltorio `rg` de Greph cubre las opciones de búsqueda y recorrido que usan la mayoría de las herramientas y los agentes. Actualmente no ofrece estas funciones de ripgrep:

- Expresiones regulares multilínea (`-U`, `--multiline`)
- Reemplazo (`-r`, `--replace`) en modo de texto (use en su lugar la reescritura AST `vendor/bin/greph`)
- Definiciones de tipos personalizadas (`--type-add`, `--type-clear`)
- Opciones de codificación (`-E`, `--encoding`)
- Scripts de filtro `--pre`
- `--sort`, `--sortr`

Si necesita una opción que falta, abra una incidencia e incluya la prueba que ejecutó con el `rg` original y el resultado esperado. Las funciones nuevas se incorporan junto con sus pruebas de referencia, de modo que la interfaz verificada siga ampliándose.

## Paridad de comportamiento

El envoltorio busca la paridad de comportamiento, no la paridad byte a byte. La salida equivale línea por línea, pero puede diferir en detalles visuales (códigos de color, truncamiento según el ancho del terminal). Las pruebas de la [matriz de funciones](https://greph.inline0.dev/es/docs/advanced/feature-matrix) comprueban la equivalencia semántica, no las diferencias exactas byte a byte.

Para los agentes y las herramientas que analizan la salida, los campos pertinentes para el analizador (ruta del archivo, número de línea, contenido, posición de coincidencia) son idénticos byte a byte a los del `rg` original en todas las pruebas verificadas.