rg 호환성

Markdown으로 보기 GitHub에서 수정 문서 위치 d105217

vendor/bin/rg은 ripgrep 스타일 호환 래퍼입니다. 가장 흔히 사용하는 ripgrep 플래그를 받아들이고, ripgrep과 동일한 방식으로 파일 트리를 순회하며 일치 결과를 출력합니다. 검증된 기능 범위는 업스트림 rg 바이너리를 대상으로 한 프로브 실행 결과를 바탕으로 재현했으며 고급 / 기능 매트릭스에 정리되어 있습니다.

이 래퍼는 얇은 CLI 변환기이며, 실제 검색 작업은 vendor/bin/greph에서 사용하는 것과 동일한 Greph\Text\TextSearcher 엔진이 수행합니다.

사용 시점

다음과 같은 경우 래퍼를 사용하세요.

이미 rg을 호출하는 기존 도구, 에이전트 또는 스크립트가 있습니다.
공유 호스팅, 보안이 강화된 컨테이너, 제한된 PaaS 등 ripgrep 자체를 설치할 수 없는 환경에서 바로 교체해 사용할 수 있는 도구가 필요합니다.
PHP만 설치된 환경에서 ripgrep의 사용 편의성을 원합니다.

다음과 같은 경우 네이티브 vendor/bin/greph을 사용하세요.

새 코드를 작성하며 ripgrep CLI 형식이 필요하지 않습니다.
래퍼가 제공하지 않는 네이티브 플래그(예: AST 모드)를 사용하려 합니다.

사용법

셸

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

인수 없이 실행하면 .을 재귀적으로 검색합니다.

셸

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

--files은 검색하지 않고 후보 파일을 나열합니다.

셸

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

JSON 출력

--json은 ripgrep이 생성하는 것과 같은 이벤트 형식의 페이로드를 출력합니다.

셸

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

stats 객체의 소요 시간은 항상 0으로 보고됩니다.

이 스키마는 다운스트림 도구가 ripgrep의 구조화된 출력을 활성화할 때 기대하는 형식입니다. 더 단순한 형식이 필요하면 대신 vendor/bin/greph --json을 사용하세요.

검증된 기능 범위

다음 플래그는 기능 매트릭스에서 rg 자체를 대상으로 검증되었습니다. 업스트림 바이너리와 래퍼는 각 프로브에서 동등한 출력을 생성합니다. 플래그에 단축형과 긴 형식이 있으면 프로브는 둘 중 하나를 사용하고, 래퍼는 두 형식을 같은 옵션으로 파싱합니다.

검색 플래그

-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

순회 플래그

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

출력 플래그

--json

프로브 없이 허용되는 옵션

래퍼는 다음 플래그도 허용하지만 아직 이를 다루는 기능 매트릭스 프로브는 없습니다.

-j N, --threads N (작업자 수, 병렬 작업자 참조)
-q, --quiet
--no-follow

제한 사항

Greph의 rg 래퍼는 대부분의 도구와 에이전트가 사용하는 검색 및 순회 기능을 지원합니다. 현재 다음 ripgrep 기능은 제공하지 않습니다.

여러 줄 정규식(-U, --multiline)
텍스트 모드의 대체(-r, --replace; 대신 vendor/bin/greph AST 재작성 사용)
사용자 지정 유형 정의(--type-add, --type-clear)
인코딩 플래그(-E, --encoding)
--pre 필터 스크립트
--sort, --sortr

누락된 플래그가 있으면 업스트림 rg을 대상으로 실행한 프로브와 예상 출력을 포함해 이슈를 등록하세요. 새 기능은 해당 기능을 검증하는 기준 프로브와 함께 추가되므로 검증된 기능 범위는 계속 넓어집니다.

동작 일치도

래퍼는 바이트 단위 일치가 아니라 동작 일치를 목표로 합니다. 출력은 줄 단위로 같지만 색상 코드나 터미널 너비에 따른 잘림 등 외관상의 세부 사항은 다를 수 있습니다. 기능 매트릭스의 프로브는 바이트 단위의 정확한 차이가 아니라 의미상 동등성을 확인합니다.

출력을 파싱하는 에이전트와 도구의 경우 파일 경로, 줄 번호, 내용, 일치 위치 등 파서에 중요한 필드는 검증된 모든 프로브에서 업스트림 rg과 바이트 단위로 동일합니다.