Vai al contenuto

Compatibilità con rg

Visualizza come Markdown Modifica su GitHub Documentazione di d105217

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

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

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

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

Shell
./vendor/bin/rg -F "function"

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

Shell
./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:

Shell
./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à. 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)
  • -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à 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.