コンテンツへスキップ

rg互換性

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

vendor/bin/rgはripgrep形式の互換ラッパーです。よく使われるripgrepフラグの大半を受け付け、ripgrepと同じようにファイルツリーをたどり、一致した内容を出力します。検証済みの機能範囲は、上流のrgバイナリに対するプローブ実行結果をもとに再現しており、詳細 / 機能マトリクスに掲載しています。

このラッパーは薄いCLIトランスレーターです。実際の検索処理は、vendor/bin/grephが使うものと同じGreph\Text\TextSearcherエンジンが行います。

使用する場面

次のような場合にラッパーを使ってください。

  • すでにrgを呼び出しているツール、エージェント、スクリプトがある。
  • ripgrep自体をインストールできない環境（共有ホスティング、セキュリティ強化済みコンテナ、制限付きPaaS）で使える、差し替え可能なツールが必要である。
  • PHPのみのインフラでripgrepの使い勝手を得たい。

次の場合はネイティブのvendor/bin/grephを使ってください。

  • 新しいコードを書く際に、ripgrepのCLI形式に合わせる必要がない。
  • ラッパーでは公開されていないネイティブフラグ（たとえばASTモード）を使いたい。

使い方

シェル
rg [options] pattern [path...]
rg --files [options] [path...]

引数なしで呼び出すと、.を再帰的に検索します。

シェル
./vendor/bin/rg -F "function"

--filesを指定すると、検索せずに候補ファイルを一覧表示します。

シェル
./vendor/bin/rg --files
./vendor/bin/rg --files --type php
./vendor/bin/rg --files --hidden

JSON出力

--jsonは、ripgrepが生成するものと同じイベント形式のデータを出力します。

シェル
./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オブジェクト内の処理時間は常にゼロとして報告されます。

これは、ripgrepの構造化出力を有効にしたときに後続ツールが期待するスキーマです。よりシンプルな形式にするには、代わりにvendor/bin/greph --jsonを使ってください。

検証済みの機能範囲

以下のフラグは、機能マトリクスで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（ワーカー数。並列ワーカーを参照）
  • -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に対して実行したプローブと期待される出力を添えて課題を報告してください。新機能は対応するオラクルプローブとともに追加され、検証済みの機能範囲が広がっていきます。

動作の互換性

このラッパーが目指すのは動作の互換性であり、バイト単位の一致ではありません。出力は行単位で同等ですが、色コードや端末幅による切り詰めなど、見た目の細部は異なる場合があります。機能マトリクスのプローブでは、バイト単位の差分ではなく意味的な同等性を確認します。

出力を解析するエージェントやツール向けに、検証済みのすべてのプローブで、パーサーが参照するフィールド（ファイルパス、行番号、内容、一致位置）は上流のrgとバイト単位で一致します。