# Compatibilità con rg

`vendor/bin/rg` è un wrapper di compatibilità in stile ripgrep. Accetta i flag ripgrep più usati, esegue la scansione dell'albero dei file come ripgrep e genera output con le corrispondenze. Le funzionalità verificate, riprodotte da test con il binario upstream `rg`, sono riportate in [Avanzate / Matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix).

Il wrapper è un traduttore CLI essenziale; la ricerca vera e propria viene eseguita dallo stesso motore `Greph\Text\TextSearcher` usato da `vendor/bin/greph`.

## Quando usarlo

Usa il wrapper quando:

- Hai uno strumento, un agente o uno script esistente che invoca già `rg`.
- Vuoi un sostituto compatibile che funzioni in ambienti in cui non puoi installare direttamente ripgrep (hosting condiviso, container con restrizioni di sicurezza, PaaS con restrizioni).
- Vuoi la praticità di ripgrep su un'infrastruttura che supporta solo PHP.

Usa `vendor/bin/greph` nativo quando:

- Stai scrivendo nuovo codice e non ti serve la struttura ripgrep CLI.
- Vuoi accedere ai flag nativi che il wrapper non espone (per esempio, la modalità AST).

## Utilizzo

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

Un'invocazione senza argomenti esegue la ricerca ricorsiva in `.`:

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

`--files` elenca i file candidati invece di eseguire la ricerca:

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

## Output JSON

`--json` genera lo stesso payload strutturato come evento prodotto da 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}}}}
```

I tempi negli oggetti `stats` sono sempre indicati come zero.

Questo è lo schema previsto dagli strumenti a valle quando abilitano l'output strutturato di ripgrep. Se preferisci una struttura più semplice, usa `vendor/bin/greph --json`.

## Funzionalità verificate

I seguenti flag sono stati verificati direttamente su `rg` nella [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix). Il binario upstream e il wrapper generano output equivalenti per ciascun test. Se un flag ha una forma breve e una lunga, il test ne usa una e il wrapper le interpreta entrambe come la stessa opzione.

### Flag di ricerca

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

### Flag di scansione

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

### Flag di output

- `--json`

### Accettati senza test

Il wrapper accetta anche i seguenti flag, che non sono ancora coperti dai test della matrice delle funzionalità:

- `-j N`, `--threads N` (numero di worker, consulta [Worker paralleli](https://greph.inline0.dev/it/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Limitazioni

Il wrapper Greph `rg` copre le funzionalità di ricerca e scansione usate dalla maggior parte degli strumenti e degli agenti. Al momento non espone le seguenti funzionalità ripgrep:

- Espressioni regolari multilinea (`-U`, `--multiline`)
- Sostituzione (`-r`, `--replace`) in modalità testuale (usa invece la riscrittura AST `vendor/bin/greph`)
- Definizioni personalizzate dei tipi (`--type-add`, `--type-clear`)
- Flag di codifica (`-E`, `--encoding`)
- Script di filtro `--pre`
- `--sort`, `--sortr`

Se ti manca un flag, segnala il problema indicando il test eseguito su `rg` upstream e l'output previsto. Le nuove funzionalità vengono aggiunte insieme ai relativi test di confronto, così le funzionalità verificate continuano ad aumentare.

## Parità di comportamento

Il wrapper punta alla parità di comportamento, non a quella byte per byte. L'output è equivalente riga per riga, ma può differire in dettagli estetici (codici colore, troncamento in base alla larghezza del terminale). I test usati per la [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix) verificano l'equivalenza semantica, non le differenze byte per byte.

Per gli agenti e gli strumenti che analizzano l'output, i campi rilevanti per il parser (percorso del file, numero di riga, contenuto, posizione della corrispondenza) sono identici byte per byte a quelli del binario upstream `rg` per ogni test verificato.