# Compatibilidade com rg

`vendor/bin/rg` é um wrapper de compatibilidade no estilo ripgrep. Ele aceita os sinalizadores ripgrep mais usados, percorre a árvore de arquivos da mesma forma que ripgrep e emite a saída correspondente. A interface verificada foi reproduzida a partir de sondagens do binário upstream `rg` e está em [Avançado / Matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix).

O wrapper é um tradutor CLI enxuto; a pesquisa propriamente dita é feita pelo mesmo mecanismo `Greph\Text\TextSearcher` usado por `vendor/bin/greph`.

## Quando usar

Use o wrapper quando:

- Você tem uma ferramenta, um agente ou um script existente que já chama `rg`.
- Você quer uma substituição direta que funcione em ambientes nos quais não é possível instalar ripgrep (hospedagem compartilhada, contêineres reforçados, PaaS restrita).
- Você quer a praticidade de ripgrep em uma infraestrutura que só oferece PHP.

Use `vendor/bin/greph` nativo quando:

- Você está escrevendo código novo e não precisa do formato ripgrep CLI.
- Você quer acesso a sinalizadores nativos que o wrapper não oferece (por exemplo, o modo AST).

## Uso

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

Uma chamada sem argumentos pesquisa `.` recursivamente:

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

`--files` lista arquivos candidatos em vez de pesquisar:

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

## Saída JSON

`--json` emite a mesma carga em formato de evento que ripgrep produz:

```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}}}}
```

Os tempos nos objetos `stats` são sempre informados como zero.

Este é o esquema esperado pelas ferramentas subsequentes quando ativam a saída estruturada de ripgrep. Para um formato mais simples, use `vendor/bin/greph --json`.

## Interface verificada

Os sinalizadores a seguir foram verificados em relação ao próprio `rg` na [matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix). O binário upstream e o wrapper produzem saídas equivalentes para cada sondagem. Quando um sinalizador tem uma forma curta e outra longa, a sondagem usa uma delas e o wrapper interpreta ambas como a mesma opção.

### Sinalizadores de pesquisa

- `-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`

### Sinalizadores do percurso

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

### Sinalizadores de saída

- `--json`

### Aceitos sem sondagem

O wrapper também aceita estes sinalizadores, mas nenhuma sondagem da matriz de recursos os cobre ainda:

- `-j N`, `--threads N` (número de workers; consulte [Workers paralelos](https://greph.inline0.dev/pt/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Limitações

O wrapper de `rg` de Greph cobre a interface de pesquisa e percurso usada pela maioria das ferramentas e agentes. No momento, não oferece os seguintes recursos ripgrep:

- Expressão regular multilinha (`-U`, `--multiline`)
- Substituição (`-r`, `--replace`) no modo de texto (use a reescrita AST `vendor/bin/greph`)
- Definições de tipo personalizadas (`--type-add`, `--type-clear`)
- Sinalizadores de codificação (`-E`, `--encoding`)
- Scripts de filtro `--pre`
- `--sort`, `--sortr`

Se estiver faltando um sinalizador, abra uma issue com a sondagem executada no `rg` upstream e a saída esperada. Os novos recursos são adicionados junto com suas sondagens de referência, ampliando a interface verificada.

## Paridade de comportamento

O wrapper busca paridade de comportamento, não paridade byte a byte. As saídas são equivalentes linha a linha, mas podem diferir em detalhes visuais (códigos de cor, truncamento pela largura do terminal). As sondagens usadas na [matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix) verificam a equivalência semântica, não diferenças byte a byte.

Para agentes e ferramentas que analisam a saída, os campos relevantes para o analisador (caminho do arquivo, número da linha, conteúdo, posição da correspondência) são idênticos byte a byte aos do `rg` upstream em cada sondagem verificada.