CLI リファレンス

Markdownとして表示 GitHubで編集ドキュメント: d105217

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書き換え。

シェル

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

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

テキストモード

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

シェル

# 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検索を参照してください。

シェル

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

シェル

# 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検索。

シェル

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

テキストインデックス

シェル

# 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/に保存されます。

インデックスセット

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

シェル

./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ファクトインデックス

シェル

./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キャッシュ

シェル

./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フラグの大半をサポートしています。検証済みの機能範囲は機能マトリクスに掲載しています。

シェル

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

例

シェル

./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フラグの大半をサポートしています。検証済みの機能範囲は機能マトリクスに掲載しています。

シェル

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 ... .）も、単発の検索として使えます。

例

シェル

./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`モードでの解析エラー）