# rg 호환성

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

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

## 사용 시점

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

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

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

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

## 사용법

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

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

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

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

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

## JSON 출력

`--json`은 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}}}}
```

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

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

## 검증된 기능 범위

다음 플래그는 [기능 매트릭스](https://greph.inline0.dev/ko/docs/advanced/feature-matrix)에서 `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` (작업자 수, [병렬 작업자](https://greph.inline0.dev/ko/docs/advanced/parallel) 참조)
- `-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`을 대상으로 실행한 프로브와 예상 출력을 포함해 이슈를 등록하세요. 새 기능은 해당 기능을 검증하는 기준 프로브와 함께 추가되므로 검증된 기능 범위는 계속 넓어집니다.

## 동작 일치도

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

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