# CLI リファレンス

Grephには4つの実行ファイルが含まれています。4つとも同じエンジンを共有し、公開するインターフェースが異なります。

| 実行ファイル | 用途 |
|---|---|
| `greph` | ネイティブのテキスト検索、AST検索、AST書き換え |
| `greph-index` | ウォーム済みテキストインデックス、ASTファクトインデックス、キャッシュ済みAST検索 |
| `rg` | ripgrep形式の互換ラッパー |
| `sg` | ast-grep形式の互換ラッパー |

例ではすべて`./vendor/bin/<binary>`のパスを使っています。依存関係としてGreph 0.2.3以降がインストールされていれば動作します。リポジトリのクローンを使う場合は`./bin/<binary>`に置き換えてください。

---

## `greph`

ネイティブのテキスト検索、AST検索、AST書き換え。

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

パスを省略すると、現在のディレクトリを検索します。

### テキストモード

デフォルトのモードです。`-F`が指定されていない限り、パターンはPCRE2正規表現として扱われます。

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

出力形式は`grep -rn`と一致します。

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

### ASTモード

`-p`を指定すると有効になります。パターンは通常のPHPで記述し、`$VAR`と`$$$VARIADIC`のメタ変数を使います。パターン文法の詳細は[モード / AST検索](https://greph.inline0.dev/ja/docs/modes/ast)を参照してください。

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

### 書き換えモード

`-p`と`-r`を組み合わせると有効になります。置換テンプレートでは検索パターンと同じメタ変数を使います。名前に対応するキャプチャ済みノードが挿入されます。

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

### オプション

| フラグ | 意味 |
|---|---|
| `-F` | 固定文字列検索（正規表現を使わない） |
| `-i` | 大文字と小文字を区別しない |
| `-w` | 単語全体に一致させる |
| `-v` | 一致条件を反転する |
| `-c` | ファイルごとの一致数を数える |
| `-l` | 一致したファイルのパスのみを一覧表示する |
| `-L` | 一致しなかったファイルのパスのみを一覧表示する |
| `-h` | テキストモードでファイル名の接頭辞を抑制する |
| `-H` | テキストモードで常にファイル名の接頭辞を表示する |
| `-n` | 行番号を表示する（デフォルト: オン） |
| `-A N` | 各一致箇所の後にN行を表示する |
| `-B N` | 各一致箇所の前にN行を表示する |
| `-C N` | 各一致箇所の前後にN行のコンテキストを表示する |
| `-m N` | ファイルごとにN件一致した時点で停止する |
| `-j N` | N個の並列ワーカーを使う |
| `-p PATTERN` | AST検索パターン |
| `-r TEMPLATE` | AST書き換えテンプレート（`-p`が必要） |
| `--glob GLOB` | パスがGLOBに一致するファイルのみを含める |
| `--type NAME` | ファイルタイプのエイリアスを含める（`php`、`js`、`md`など） |
| `--type-not NAME` | ファイルタイプのエイリアスを除外する |
| `--lang NAME` | AST言語。デフォルト: `php` |
| `--json` | JSON出力を生成する |
| `--no-ignore` | `.gitignore`および`.grephignore`のルールを無視する |
| `--hidden` | 隠しファイルを含める |
| `--dry-run` | ファイルに書き込まずに書き換え結果を表示する |
| `--interactive` | 書き換えるファイルごとに確認する |
| `--help` | インラインの使用方法を表示する |

---

## `greph-index`

ウォーム済みテキストインデックス、ASTファクトインデックス、キャッシュ済みAST検索。

```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...]
```

### テキストインデックス

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

テキストインデックスは、トライグラムと識別子の転置リストを保存するウォーム済みストアです。デフォルトではインデックス対象ルートの`.greph-index/`に保存されます。

### インデックスセット

インデックスセットを使うと、複数のインデックスを繰り返し使うワークフローを名前付きマニフェストにまとめられます。

```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)' .
```

デフォルトのマニフェストファイルは`.greph-index-set.json`です。各エントリはルート、モード、ライフサイクルプロファイルを指定します。`set build`と`set refresh`は有効なエントリを対象に動作します。`set search`は選択したエントリ全体を検索し、重複する一致を除去します。

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

ASTファクトインデックスは、ノードレベルの情報（呼び出し、インスタンス化、クラス、メソッド）を抽出し、クエリ可能なストアに保存します。検索ではファクトキーに基づいてO(log n)を行い、その後ソースに照らして検証します。デフォルトでは`.greph-ast-index/`に保存されます。

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

ASTキャッシュは解析済みツリーをディスクに保存するため、検索時にパーサーを完全にスキップできます。デフォルトでは`.greph-ast-cache/`に保存されます。

### オプション

テキスト検索のオプションは`greph`のフラグセット（`-F`、`-i`、`-w`、`-v`、`-c`、`-l`、`-L`、`-A`、`-B`、`-C`、`-m`、`--glob`、`--type`、`--type-not`、`--json`、`--no-ignore`、`--hidden`）に準拠します。

追加のフラグ:

| フラグ | 意味 |
|---|---|
| `--index-dir DIR` | デフォルト以外のウォーム済みインデックスディレクトリを使う。複数インデックス検索と統計情報では複数回指定可能。 |
| `--lifecycle PROFILE` | ビルドポリシー: `static`、`manual-refresh`、`opportunistic-refresh`、`strict-stale-check` |
| `--auto-refresh-max-files N` | 便宜的な更新を行うファイル数のしきい値 |
| `--auto-refresh-max-bytes N` | 便宜的な更新を行うバイト数のしきい値 |
| `--manifest FILE` | インデックスセットのマニフェストを読み込む。デフォルト: `.greph-index-set.json` |
| `--mode MODE` | セット操作の対象を`text`、`ast-index`、または`ast-cache`に限定する |
| `--index NAME` | セット操作の対象を名前付きマニフェストエントリに限定する。複数回指定可能。 |
| `--show-index-origin` | ウォーム済みの複数インデックスまたはセットの出力に、一致したインデックスエントリ名を接頭辞として付ける |
| `--trace-plan` | ウォーム済みプランナーの診断情報を`stderr`に出力する |
| `--dry-refresh` | `stats`で、何も変更せずにウォーム済み検索の動作を報告する |
| `--lang NAME` | `ast-index` / `ast-cache`検索のAST言語。デフォルト: `php` |
| `-j N`、`--jobs N` | ASTスキャンに使うワーカー数 |
| `-l`、`--files-with-matches` | 一致したファイルのパスのみを一覧表示する（ASTモード） |
| `--strict-parse` | 解析エラーをスキップせずに失敗とする |
| `--fallback MODE` | インデックスがない場合の動作: `fail`（デフォルト）または`scan` |
| `--help` | インラインの使用方法を表示する |

---

## `rg`

ripgrep形式の互換ラッパーです。よく使われるripgrepフラグの大半をサポートしています。検証済みの機能範囲は[機能マトリクス](https://greph.inline0.dev/ja/docs/advanced/feature-matrix)に掲載しています。

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

### 例

```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" .
```

### サポートされるオプション

| フラグ | 意味 |
|---|---|
| `-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` | 各一致箇所の後にN行を表示する |
| `-B N`、`--before-context N` | 各一致箇所の前にN行を表示する |
| `-C N`、`--context N` | 各一致箇所の前後にN行を表示する |
| `-m N`、`--max-count N` | ファイルごとにN件一致した時点で停止する |
| `-j N`、`--threads N` | N個の並列ワーカーを使う |
| `-e P`、`--regexp P` | 検索パターン |
| `-L`、`--follow` | シンボリックリンクをたどる |
| `--glob GLOB` | パスがGLOBに一致するファイルのみを含める |
| `--type NAME` | ファイルタイプを含める |
| `--type-not NAME` | ファイルタイプを除外する |
| `--json` | ripgrep形式のJSONイベントを生成する |
| `--no-ignore` | `.gitignore`および`.grephignore`のルールを無視する |
| `--hidden` | 隠しファイルを含める |
| `--files` | 検索せずに候補ファイルを一覧表示する |
| `--help` | インラインの使用方法を表示する |

---

## `sg`

ast-grep形式の互換ラッパーです。よく使われるast-grepフラグの大半をサポートしています。検証済みの機能範囲は[機能マトリクス](https://greph.inline0.dev/ja/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`はast-grepの標準的な動詞です。`scan`と`rewrite`は、一般的な使い方に合わせたラッパー専用の別名です。引数なしの呼び出し（`sg --pattern ... .`）も、単発の検索として使えます。

### 例

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

### サポートされるオプション

| フラグ | 意味 |
|---|---|
| `-p`、`--pattern PATTERN` | ASTパターン |
| `-r`、`--rewrite TEMPLATE` | 書き換えテンプレート |
| `-l`、`--lang NAME` | AST言語。デフォルト: `php` |
| `-j`、`--threads N` | N個の並列ワーカーを使う |
| `-i`、`--interactive` | 書き換えごとに確認する |
| `-U`、`--update-all` | 確認なしで書き換えを適用する |
| `--files-with-matches` | 一致があるファイルのパスのみを表示する |
| `--json[=STYLE]` | JSON出力を生成する。STYLE = `pretty`、`stream`、または`compact` |
| `--no-ignore [MODE]` | リポジトリの無視ルールを無視する |
| `--hidden` | 隠しファイルを含める |
| `--glob GLOB`、`--globs GLOB` | パスがGLOBに一致するファイルのみを含める |
| `--type NAME` | ファイルタイプを含める |
| `--type-not NAME` | ファイルタイプを除外する |
| `--dry-run` | ファイルに書き込まずに書き換えをプレビューする |
| `--help` | インラインの使用方法を表示する |

---

## 終了コード

Grephはgrep / ripgrepの規則に従います。

| コード | 意味 |
|---|---|
| `0` | 一致が1件以上見つかった（書き換えの場合は、ファイルが1つ以上変更された） |
| `1` | 一致が見つからなかった |
| `2` | 使用方法の誤りまたは実行時エラー（引数の誤り、インデックスがない、`--strict-parse`モードでの解析エラー） |