Pular para o conteúdo

Compatibilidade com rg

Ver como Markdown Editar no GitHub Documentação em d105217

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.

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

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

Uma chamada sem argumentos pesquisa . recursivamente:

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

--files lista arquivos candidatos em vez de pesquisar:

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

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

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. 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)
  • -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 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.