# Kompatibilitas rg

`vendor/bin/rg` adalah pembungkus kompatibilitas bergaya ripgrep. Pembungkus ini menerima flag ripgrep yang paling umum digunakan, menelusuri pohon file dengan cara yang sama seperti ripgrep, dan menghasilkan output yang cocok. Antarmuka yang telah diverifikasi berasal dari uji probe terhadap biner upstream `rg` dan tersedia di [Lanjutan / Matriks Fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix).

Pembungkus ini adalah penerjemah CLI yang tipis; pekerjaan pencarian sebenarnya dilakukan oleh mesin `Greph\Text\TextSearcher` yang sama dengan yang digunakan `vendor/bin/greph`.

## Kapan menggunakannya

Gunakan pembungkus jika:

- Anda memiliki alat, agen, atau skrip yang sudah menjalankan `rg`.
- Anda menginginkan pengganti siap pakai yang berfungsi di lingkungan tempat Anda tidak dapat memasang ripgrep itu sendiri (hosting bersama, kontainer yang diperketat, PaaS terbatas).
- Anda menginginkan kemudahan penggunaan ripgrep pada infrastruktur khusus PHP.

Gunakan `vendor/bin/greph` native jika:

- Anda sedang menulis kode baru dan tidak memerlukan bentuk ripgrep CLI.
- Anda ingin mengakses flag native yang tidak disediakan pembungkus (misalnya mode AST).

## Penggunaan

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

Pemanggilan tanpa argumen tambahan akan menelusuri `.` secara rekursif:

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

`--files` menampilkan daftar file kandidat alih-alih melakukan pencarian:

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

## Output JSON

`--json` menghasilkan payload berbentuk event yang sama seperti yang dihasilkan 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}}}}
```

Waktu dalam objek `stats` selalu dilaporkan sebagai nol.

Inilah skema yang diharapkan oleh alat hilir saat mengaktifkan output terstruktur milik ripgrep. Jika Anda menginginkan bentuk yang lebih sederhana, gunakan `vendor/bin/greph --json`.

## Antarmuka yang diverifikasi

Flag berikut telah diverifikasi terhadap `rg` itu sendiri dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix). Biner upstream dan pembungkus menghasilkan output yang setara untuk setiap probe. Jika sebuah flag memiliki ejaan pendek dan panjang, probe menggunakan salah satunya dan pembungkus mengurai keduanya sebagai opsi yang sama.

### Flag pencarian

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

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

### Flag output

- `--json`

### Diterima tanpa probe

Pembungkus juga menerima flag berikut, tetapi belum ada probe matriks fitur yang mencakupnya:

- `-j N`, `--threads N` (jumlah pekerja, lihat [Pekerja Paralel](https://greph.inline0.dev/id/docs/advanced/parallel))
- `-q`, `--quiet`
- `--no-follow`

## Batasan

Pembungkus `rg` milik Greph mencakup permukaan pencarian dan penelusuran yang digunakan sebagian besar alat dan agen. Saat ini, pembungkus tersebut belum menyediakan fitur ripgrep berikut:

- Regex multibaris (`-U`, `--multiline`)
- Penggantian (`-r`, `--replace`) untuk mode teks (gunakan penulisan ulang AST `vendor/bin/greph` sebagai gantinya)
- Definisi tipe khusus (`--type-add`, `--type-clear`)
- Flag pengodean (`-E`, `--encoding`)
- Skrip filter `--pre`
- `--sort`, `--sortr`

Jika Anda menemukan flag yang belum tersedia, ajukan issue dengan probe yang Anda jalankan terhadap upstream `rg` dan output yang diharapkan. Fitur baru ditambahkan bersama probe acuannya agar cakupan yang telah diverifikasi terus bertambah.

## Kesetaraan perilaku

Pembungkus ini menargetkan kesetaraan perilaku, bukan kesetaraan byte. Output setara pada tingkat baris, tetapi dapat berbeda dalam detail kosmetik (kode warna, pemotongan lebar terminal). Probe dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix) memeriksa kesetaraan semantik, bukan perbedaan yang sama persis per byte.

Untuk agen dan alat yang mengurai output, field yang relevan bagi parser (jalur file, nomor baris, konten, posisi kecocokan) identik per byte dengan upstream `rg` untuk setiap probe yang diverifikasi.