ripgrep

ripgrep

テキスト検索には grep より rg を優先し、実際のタスクがパスの特定である場合は find | grep より rg --files を優先してください。

2026年4月10日に ripgrep 15.1.0 でローカル検証済みです。このスキルは特定のリポジトリに依存しませんが、例では Unix 系シェルと PATH に含まれる rg バイナリを想定しています。

判断ツリー

どのような検索が必要ですか？

• ファイルの内容からテキスト、シンボル、正規表現、またはリテラルを検索する

  • rg から始めます
  • references/commands.md を読みます

• ファイルの内容を読まずにファイル名やパスを見つける

  • rg --files [path] から始めます
  • 必要に応じて、その一覧を2つ目の rg で絞り込みます
  • references/patterns.md を読みます

• 特定の言語、glob、隠しファイル、無視対象ファイル、圧縮データ、または複数行ブロックだけを検索する

  • references/commands.md を読みます
  • 結果が想定と異なる、または見つからない場合は、references/gotchas.md を読みます

• 設定ファイル、エイリアス、またはカスタムファイルタイプを使って、ripgrep の動作を再現可能にする

  • references/configuration.md を読みます

• 結果を自動化処理、スクリプト、エディター、またはその他のツールに渡す

  • 適切に --json、-0、-l、--count-matches、または --sort path を優先します
  • references/patterns.md を読みます

• ユーザーがファイル全体の読み込み、構造化 JSON のクエリ、またはファイルシステムのメタデータを求めている

  • rg が不得意な用途に無理に使わないでください
  • ファイルを直接読むか、jq、find、または fd を使います

デフォルトの運用ルール

1. テキスト検索には、まず rg を使います。rg が利用できない場合、または POSIX grep の厳密な動作が本当に必要な場合に限り、grep に切り替えます。
2. ユーザーが明らかに正規表現としての動作を求めている場合を除き、ユーザー指定のリテラルには -F を使います。
3. ツリー全体を検索して後から整理するのではなく、明示的なパスと -t または -g を使って、早い段階で検索範囲を絞り込みます。
4. パスの特定には rg --files を使い、find ... | grep ... を組み立てる代わりに、パイプで別の rg に渡してファイル名を絞り込みます。
5. 既知の対象範囲に応じて無視設定を選びます。通常の走査には何も指定せず、隠し項目には --hidden、無視対象には -u または --no-ignore、必要に応じて両方を使います。既知のファイルは直接検索し、そこにたどり着くためだけに失敗する中間検索を実行しないでください。-uuu などのバイナリー検索の上書きは、実際にバイナリー検索が必要な場合に限って使います。
6. 結果が見つからず、ripgrep が何をスキップしたのか確認する必要がある場合は、--debug を使います。
7. 機械処理には --json または -n --color never --no-heading を使います。最大速度より出力の決定性が重要な場合は、--sort path を優先します。

クイックリファレンス

必要な検索	コマンド	備考
リテラルテキスト検索	rg -n -F 'needle' path/	句読点を含むユーザー指定文字列に最適なデフォルトです
正規表現検索	rg -n 'foo\\s+bar' path/	シェルの干渉を避けるため、シングルクォートを使います
ファイル名のみ	rg --files path/	デフォルトで無視ファイルに従います
ファイル名の絞り込み	`rg --files	rg '(^
特定の言語に一致	rg -n -t py 'pattern' src/	-t は対象に含め、-T は対象から除外します
特定の glob に一致	rg -n -g '*.tsx' 'pattern' src/	後の glob が前の glob を上書きします
隠しファイルまたは無視対象の内容を検索	rg --hidden 'pattern' path/、rg -u 'pattern' path/、または rg --hidden --no-ignore 'pattern' path/	必要なフィルターの上書きを直接選びます。既知のファイルパスは明示的に検索できます
一致する内容を含むファイル	rg -l 'pattern' path/	ファイルを開く前に使います
個々の一致数を数える	rg --count-matches 'pattern' path/	-c は一致数ではなく、一致した行数を数えます
機械可読な出力	rg --json 'pattern' path/	ツールやスクリプトに最適です
先読み、後読み、または後方参照	rg -P '...' path/	ビルドに PCRE2 サポートが必要です
複数行ブロック	rg -U '(?s)start.*end' file	複数行検索は処理が遅く、より多くのメモリを消費します
スキップされたファイルの診断	rg --debug 'pattern' path/	無視およびスキップの理由を表示します

読み方ガイド

タスク	参照先
正しいコマンド、フラグ、または出力モード	references/commands.md
設定ファイル、エイリアス、カスタムタイプ、環境設定	references/configuration.md
エージェントによる検索ワークフロー、ファイル名の検出、シェルパイプライン、決定的な出力	references/patterns.md
検索結果が見つからない、引用符の問題、複数行での予期しない挙動、JSON の制限、その他の落とし穴	references/gotchas.md

検証済みの動作

1. rg --files はデフォルトで無視ルールを尊重し、ローカルでの検証では無視対象の logs/app.log を除外しました。
2. .rgignore は .ignore より優先され、--no-ignore を指定すると同じ無視対象ファイルにアクセスできました。
3. --hidden を指定すると、無視処理を無効にせずに隠しコンテンツを表示できました。
4. -g フラグの順序によって結果セットが変わる動作は、上流のドキュメントどおりでした。後のグロブが先のグロブを上書きしました。
5. RIPGREP_CONFIG_PATH によって、設定ファイルから --smart-case とカスタムの web タイプが正常に読み込まれました。
6. --json は、begin、match、end、summary のメッセージを JSON Lines 形式で出力しました。
7. -U '(?s)...' は複数行にまたがってマッチし、このマシンではローカルビルドに PCRE2 が含まれていたため、-P の先読み・後読みも機能しました。

落とし穴

1. rg は POSIX の grep とバイト単位で完全に置き換え可能なものではありません。速度、再帰検索、無視処理、または Unicode 対応の正規表現が重要な場合に、デフォルトの検索ツールとして使います。
2. 検索結果が見つからない場合、ripgrep のバグであるよりも、無視ルール、隠しファイル、グロブの順序、または引用符の問題であることがほとんどです。原因が分かっている場合は該当する修正を直接選び、スキップの理由が不明な場合は --debug を使います。
3. --replace は出力表示のみを変更します。ファイルは編集しません。
4. --json は検索結果用であり、すべての出力モードに使えるわけではありません。--files、-l、-c とは併用できません。
5. -P と -U は強力ですが、デフォルトのエンジンや通常の行単位の検索より負荷が高くなります。意図を持って使ってください。

ヘルパースクリプト

• scripts/probe_ripgrep.py は一時的なコーパスを作成し、無視ルールの優先順位、JSON 出力、複数行マッチ、PCRE2 のサポートなど、実際の rg の動作を検証します。
• scripts/validate.py は構造、フロントマター、参照、必須ファイル、Python の構文をチェックします。
• scripts/test_skill.py は検証を実行し、評価範囲をチェックして相互参照を検証し、ripgrep のプローブテスト一式を実行します。

ガイダンスで解決できない場合

例がインストール済みビルドの動作と一致しない場合は、rg --version、rg --help、有効な設定、関連する公式ドキュメントを確認してください。機密情報を含まない小さなコーパスを使い、バージョン変更と無視ルールまたは引用符の誤りを切り分けます。その根拠と再現手順を添えて、正規のスキル修正を提案し、裏付けのない動作は明示したままにします。インストール済みのコピーを黙って編集したり、主張の裏付けのために検索対象を秘密情報を含む可能性のあるパスに広げたりしないでください。