# Referensi CLI

Greph menyediakan empat executable. Keempatnya menggunakan mesin yang sama; perbedaannya terletak pada antarmuka yang disediakan.

| Biner | Tujuan |
|---|---|
| `greph` | Pencarian teks native, pencarian AST, dan penulisan ulang AST |
| `greph-index` | Indeks teks yang telah dipanaskan, indeks fakta AST, dan pencarian AST dalam cache |
| `rg` | Pembungkus kompatibilitas bergaya ripgrep |
| `sg` | Pembungkus kompatibilitas bergaya ast-grep |

Semua jalur dalam contoh menggunakan `./vendor/bin/<binary>`, yang berfungsi dengan Greph 0.2.3 atau yang diinstal kemudian sebagai dependensi. Ganti dengan `./bin/<binary>` jika Anda bekerja dari klona repositori.

---

## `greph`

Pencarian teks native, pencarian AST, dan penulisan ulang AST.

```bash
greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]
```

Jika jalur tidak dicantumkan, direktori saat ini akan ditelusuri.

### Mode teks

Mode default. Pola berupa regex PCRE2 kecuali `-F` diaktifkan.

```bash
# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src
```

Format output cocok dengan `grep -rn`:

```text
src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...
```

### Mode AST

Diaktifkan dengan `-p`. Pola ditulis sebagai PHP biasa dengan metavariabel `$VAR` dan `$$$VARIADIC`. Lihat [Mode / Pencarian AST](https://greph.inline0.dev/id/docs/modes/ast) untuk tata bahasa pola lengkap.

```bash
./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src
```

### Mode penulisan ulang

Diaktifkan dengan menggabungkan `-p` dan `-r`. Templat pengganti menggunakan metavariabel yang sama dengan pola pencarian; node yang ditangkap disisipkan berdasarkan nama.

```bash
# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

### Opsi

| Flag | Arti |
|---|---|
| `-F` | Pencarian string tetap (tanpa regex) |
| `-i` | Pencocokan tanpa membedakan huruf besar-kecil |
| `-w` | Pencocokan kata utuh |
| `-v` | Balikkan pencocokan |
| `-c` | Hitung pencocokan per file |
| `-l` | Hanya tampilkan jalur file yang cocok |
| `-L` | Hanya tampilkan jalur file yang tidak cocok |
| `-h` | Sembunyikan awalan nama file dalam mode teks |
| `-H` | Selalu tampilkan awalan nama file dalam mode teks |
| `-n` | Tampilkan nomor baris (default: aktif) |
| `-A N` | Tampilkan N baris setelah setiap kecocokan |
| `-B N` | Tampilkan N baris sebelum setiap kecocokan |
| `-C N` | Tampilkan N baris konteks sebelum dan sesudah setiap kecocokan |
| `-m N` | Berhenti setelah N kecocokan per file |
| `-j N` | Gunakan N pekerja paralel |
| `-p PATTERN` | Pola pencarian AST |
| `-r TEMPLATE` | Templat penulisan ulang AST (memerlukan `-p`) |
| `--glob GLOB` | Hanya sertakan file dengan jalur yang cocok dengan GLOB |
| `--type NAME` | Sertakan alias tipe file (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Kecualikan alias tipe file |
| `--lang NAME` | Bahasa AST. Default: `php` |
| `--json` | Hasilkan output JSON |
| `--no-ignore` | Abaikan aturan `.gitignore` dan `.grephignore` |
| `--hidden` | Sertakan file tersembunyi |
| `--dry-run` | Tampilkan penulisan ulang tanpa menulis file |
| `--interactive` | Konfirmasikan setiap file yang ditulis ulang |
| `--help` | Tampilkan penggunaan inline |

---

## `greph-index`

Indeks teks yang telah dipanaskan, indeks fakta AST, dan pencarian AST dalam cache.

```bash
greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]
```

### Indeks teks

```bash
# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin
```

Indeks teks adalah penyimpanan posting trigram + identifier yang telah dipanaskan. Secara default, indeks berada di `.greph-index/` dalam root yang diindeks.

### Kumpulan indeks

Kumpulan indeks mengubah alur kerja berulang dengan beberapa indeks menjadi manifes bernama:

```bash
./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .
```

File manifes default adalah `.greph-index-set.json`. Setiap entri menunjuk ke root, mode, dan profil siklus hidup. `set build` dan `set refresh` beroperasi pada entri yang diaktifkan; `set search` menjalankan operasi pada entri yang dipilih dan menghapus kecocokan yang tumpang tindih.

### Indeks fakta AST

```bash
./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin
```

Indeks fakta AST mengekstrak fakta tingkat node (pemanggilan, instansiasi, kelas, metode) ke dalam penyimpanan yang dapat dikueri. Pencarian dilakukan dengan O(log n) pada kunci fakta, lalu diverifikasi terhadap sumber. Secara default, disimpan di `.greph-ast-index/`.

### Cache AST

```bash
./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src
```

Cache AST menyimpan pohon yang telah diparse di disk sehingga pencarian dapat melewati parser sepenuhnya. Secara default, disimpan di `.greph-ast-cache/`.

### Opsi

Opsi pencarian teks cocok dengan kumpulan flag `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Flag tambahan:

| Flag | Arti |
|---|---|
| `--index-dir DIR` | Gunakan direktori indeks hangat nondefault. Dapat diulang untuk pencarian dan statistik multiindeks. |
| `--lifecycle PROFILE` | Kebijakan build: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Ambang batas file untuk penyegaran oportunistik |
| `--auto-refresh-max-bytes N` | Ambang batas byte untuk penyegaran oportunistik |
| `--manifest FILE` | Muat manifes kumpulan indeks. Default: `.greph-index-set.json` |
| `--mode MODE` | Batasi operasi kumpulan ke `text`, `ast-index`, atau `ast-cache` |
| `--index NAME` | Batasi operasi kumpulan ke entri manifes bernama. Dapat diulang. |
| `--show-index-origin` | Awali output multiindeks hangat atau kumpulan dengan nama entri indeks yang cocok |
| `--trace-plan` | Hasilkan diagnostik perencana hangat ke `stderr` |
| `--dry-refresh` | Dalam `stats`, laporkan tindakan pencarian hangat tanpa mengubah apa pun |
| `--lang NAME` | Bahasa AST untuk pencarian `ast-index` / `ast-cache`. Default: `php` |
| `-j N`, `--jobs N` | Pekerja untuk pemindaian AST |
| `-l`, `--files-with-matches` | Hanya tampilkan jalur file yang cocok (mode AST) |
| `--strict-parse` | Gagalkan proses saat terjadi kesalahan parse, alih-alih melewati file |
| `--fallback MODE` | Perilaku saat indeks tidak ditemukan: `fail` (default) atau `scan` |
| `--help` | Tampilkan penggunaan inline |

---

## `rg`

Pembungkus kompatibilitas bergaya ripgrep. Mendukung flag ripgrep yang paling umum digunakan. Antarmuka yang telah diverifikasi diterbitkan dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix).

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

### Contoh

```bash
./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .
```

### Opsi yang didukung

| Flag | Arti |
|---|---|
| `-F`, `--fixed-strings` | Pencarian string tetap |
| `-i`, `--ignore-case` | Pencarian tanpa membedakan huruf besar-kecil |
| `-w`, `--word-regexp` | Pencarian kata utuh |
| `-v`, `--invert-match` | Balikkan kecocokan |
| `-c`, `--count` | Hitung baris yang cocok |
| `-l`, `--files-with-matches` | Daftarkan file yang cocok |
| `--files-without-match` | Daftarkan file yang tidak cocok |
| `-I`, `--no-filename` | Sembunyikan awalan nama file |
| `-H`, `--with-filename` | Selalu tampilkan awalan nama file |
| `-n`, `--line-number` | Tampilkan nomor baris |
| `-A N`, `--after-context N` | Tampilkan N baris setelah setiap kecocokan |
| `-B N`, `--before-context N` | Tampilkan N baris sebelum setiap kecocokan |
| `-C N`, `--context N` | Tampilkan N baris sebelum dan sesudah setiap kecocokan |
| `-m N`, `--max-count N` | Berhenti setelah N kecocokan per file |
| `-j N`, `--threads N` | Gunakan N pekerja paralel |
| `-e P`, `--regexp P` | Pola pencarian |
| `-L`, `--follow` | Ikuti symlink |
| `--glob GLOB` | Hanya sertakan file dengan jalur yang cocok dengan GLOB |
| `--type NAME` | Sertakan tipe file |
| `--type-not NAME` | Kecualikan tipe file |
| `--json` | Hasilkan ripgrep-event bergaya JSON |
| `--no-ignore` | Abaikan aturan `.gitignore` dan `.grephignore` |
| `--hidden` | Sertakan file tersembunyi |
| `--files` | Daftarkan file kandidat alih-alih melakukan pencarian |
| `--help` | Tampilkan penggunaan inline |

---

## `sg`

Pembungkus kompatibilitas bergaya ast-grep. Mendukung flag ast-grep yang paling umum digunakan. Antarmuka yang telah diverifikasi diterbitkan dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix).

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` adalah kata kerja ast-grep kanonis. `scan` dan `rewrite` adalah alias khusus pembungkus yang mencerminkan penggunaan umum. Pemanggilan tanpa argumen tambahan (`sg --pattern ... .`) juga berfungsi sebagai pencarian sekali jalan.

### Contoh

```bash
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php
```

### Opsi yang didukung

| Flag | Arti |
|---|---|
| `-p`, `--pattern PATTERN` | Pola AST |
| `-r`, `--rewrite TEMPLATE` | Templat penulisan ulang |
| `-l`, `--lang NAME` | Bahasa AST. Default: `php` |
| `-j`, `--threads N` | Gunakan N pekerja paralel |
| `-i`, `--interactive` | Konfirmasikan setiap penulisan ulang |
| `-U`, `--update-all` | Terapkan penulisan ulang tanpa konfirmasi |
| `--files-with-matches` | Hanya tampilkan jalur file yang berisi kecocokan |
| `--json[=STYLE]` | Hasilkan output JSON. STYLE = `pretty`, `stream`, atau `compact` |
| `--no-ignore [MODE]` | Abaikan aturan pengabaian repositori |
| `--hidden` | Sertakan file tersembunyi |
| `--glob GLOB`, `--globs GLOB` | Hanya sertakan file dengan jalur yang cocok dengan GLOB |
| `--type NAME` | Sertakan tipe file |
| `--type-not NAME` | Kecualikan tipe file |
| `--dry-run` | Pratinjau penulisan ulang tanpa menulis file |
| `--help` | Tampilkan penggunaan inline |

---

## Kode keluar

Greph mengikuti konvensi grep / ripgrep:

| Kode | Arti |
|---|---|
| `0` | Setidaknya satu kecocokan ditemukan (atau, untuk penulisan ulang, setidaknya satu file berubah) |
| `1` | Tidak ada kecocokan yang ditemukan |
| `2` | Kesalahan penggunaan atau kegagalan saat dijalankan (argumen buruk, indeks tidak ditemukan, kesalahan parse dalam mode `--strict-parse`) |