# Compatibilité avec rg

`vendor/bin/rg` est une enveloppe de compatibilité de type ripgrep. Elle accepte les options ripgrep les plus couramment utilisées, parcourt l’arborescence des fichiers comme le fait ripgrep et produit les résultats correspondants. Les fonctionnalités vérifiées sont reproduites à partir de tests exploratoires du binaire `rg` en amont et sont répertoriées dans [Avancé / Matrice des fonctionnalités](https://greph.inline0.dev/fr/docs/advanced/feature-matrix).

L’enveloppe est un simple traducteur de CLI ; la recherche elle-même est effectuée par le même moteur `Greph\Text\TextSearcher` qu’utilise `vendor/bin/greph`.

## Quand l’utiliser

Utilisez l’enveloppe si :

- Vous avez déjà un outil, un agent ou un script qui appelle `rg`.
- Vous voulez un remplacement direct qui fonctionne dans des environnements où vous ne pouvez pas installer ripgrep lui-même (hébergement mutualisé, conteneurs renforcés, PaaS restreint).
- Vous souhaitez bénéficier de l’ergonomie de ripgrep sur une infrastructure limitée à PHP.

Utilisez `vendor/bin/greph` en natif si :

- Vous écrivez du nouveau code et n’avez pas besoin de la forme ripgrep CLI.
- Vous voulez accéder aux options natives que l’enveloppe ne propose pas (par exemple, le mode AST).

## Utilisation

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

Un appel sans argument lance une recherche récursive dans `.` :

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

`--files` liste les fichiers candidats au lieu d’effectuer une recherche :

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

## Sortie JSON

`--json` émet une charge utile structurée en événements identique à celle produite par 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}}}}
```

Les durées des objets `stats` sont toujours indiquées comme étant nulles.

Il s’agit du schéma attendu par les outils en aval qui activent la sortie structurée de ripgrep. Pour une structure plus simple, utilisez plutôt `vendor/bin/greph --json`.

## Fonctionnalités vérifiées

Les options suivantes ont été vérifiées par rapport à `rg` lui-même dans la [matrice des fonctionnalités](https://greph.inline0.dev/fr/docs/advanced/feature-matrix). Le binaire en amont et l’enveloppe produisent des résultats équivalents pour chaque test. Lorsqu’une option possède une forme courte et une forme longue, le test en utilise une seule et l’enveloppe les interprète toutes deux comme la même option.

### Options de recherche

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

### Options de parcours

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

### Options de sortie

- `--json`

### Options acceptées sans test

L’enveloppe accepte également les options suivantes, qui ne sont toutefois pas encore couvertes par un test de la matrice des fonctionnalités :

- `-j N`, `--threads N` (nombre de processus de travail, voir [Processus de travail en parallèle](https://greph.inline0.dev/fr/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Limites

L’enveloppe `rg` de Greph couvre les fonctionnalités de recherche et de parcours utilisées par la plupart des outils et agents. Elle ne propose actuellement pas les fonctionnalités ripgrep suivantes :

- Expressions régulières multilignes (`-U`, `--multiline`)
- Remplacement (`-r`, `--replace`) en mode texte (utilisez plutôt la réécriture AST `vendor/bin/greph`)
- Définitions de types personnalisées (`--type-add`, `--type-clear`)
- Options d’encodage (`-E`, `--encoding`)
- Scripts de filtre `--pre`
- `--sort`, `--sortr`

Si une option vous manque, signalez le problème en indiquant le test exécuté sur `rg` en amont et le résultat attendu. Les nouvelles fonctionnalités sont accompagnées de tests de référence, ce qui permet d’étendre continuellement l’ensemble des fonctionnalités vérifiées.

## Parité de comportement

L’enveloppe vise la parité de comportement, pas la parité octet par octet. Les lignes de sortie sont équivalentes, mais certains détails visuels peuvent différer (codes couleur, troncature selon la largeur du terminal). Les tests utilisés dans la [matrice des fonctionnalités](https://greph.inline0.dev/fr/docs/advanced/feature-matrix) vérifient l’équivalence sémantique, et non une comparaison exacte des octets.

Pour les agents et les outils qui analysent la sortie, les champs pertinents pour l’analyse (chemin du fichier, numéro de ligne, contenu, position de la correspondance) sont identiques octet par octet à ceux de `rg` en amont pour chaque test vérifié.