Claude Code respectGitignoreとは — Grep/Globには効かない設定

respectGitignore はsettings.jsonのキーで、制御対象は @ メンションのファイルピッカーだけです。GrepやGlobの検索結果には影響しません。この3つを1つの設定で動くと思い込むと、意図した除外ができずに戸惑います。挙動はツールごとに違い、しかも既定値が逆向きです。

この設定はv2.1.0で追加されました。それ以前は @ の候補にgitignore対象のファイルが混ざるかどうかを、プロジェクトごとに選ぶ手段がありませんでした。追加の経緯自体は単純ですが、同じタイミングでGlob・Grepの挙動が変わったわけではないため、3つの仕組みの関係が分かりにくいまま残っています。

respectGitignoreは@候補だけを絞る設定

respectGitignore は、コード入力欄で @ を押したときに出るファイル候補から、.gitignore に一致するファイルを外すかどうかを決める設定です。既定値は true です。node_modules やビルド成果物のような追跡外ファイルは、この既定のままなら候補に出ません。

{
  "respectGitignore": true
}

false にすると、gitignore対象のファイルも候補に含まれるようになります。ローカルのみで使う設定ファイルやビルド出力を明示的に @ で渡したいときに有効です。ただし秘密情報を含むファイルまで候補に出てしまうため、必要な場面だけ一時的に切り替える運用のほうが安全です。この設定が制御するのは候補の一覧だけで、Claudeが実際に読み書きできるファイルの範囲そのものは変わりません。gitignore対象のファイルでも、パスさえ渡せばRead・Editはそのまま動きます。

配置場所は他のsettings.jsonキーと同じ3階層です。プロジェクト共有にすればチーム全員に同じ候補表示を強制でき、個人だけ変えたいなら settings.local.json に置きます。設定ファイルの優先順位や階層の使い分けはClaude Code設定ガイドにまとめています。

Grep・Globは対象外、挙動もツールで逆

respectGitignore が効くのは @ の候補表示だけです。ClaudeがコードベースをGrepやGlobで検索するとき、この設定は一切参照されません。しかも厄介なことに、GlobとGrepは既定の挙動そのものが逆になっています。

Globはファイル名でパターン一致するツールです。既定では .gitignore を無視し、追跡外のファイルも含めて全部見つけます。デバッグ中にビルド成果物やログファイルまで名前で拾いたい場面を優先した挙動です。一方Grepはファイル内容を検索するツールで、既定で .gitignore を尊重し、追跡外のディレクトリを飛ばします。node_modules 配下がヒットに混ざって埋もれるのを防ぐための挙動です。同じ「検索」という言葉でも、名前で探すか中身で探すかで、gitignoreの扱いが逆に設計されています。

具体例で見ると分かりやすくなります。.env を .gitignore に登録している場合、Globでファイル名を検索すると .env はそのままヒットします。反対に、.env の中身をGrepでパターン検索すると、ファイルパスを明示しない限りヒットしません。同じファイルなのに、名前で探すか中身で探すかで結果が変わるのは、この既定値の非対称が理由です。

CLAUDE_CODE_GLOB_NO_IGNOREでGlobを変える

Globにもgitignoreを守らせたいときは、respectGitignore ではなく環境変数 CLAUDE_CODE_GLOB_NO_IGNORE を使います。名前の通り「無視しない」を制御する変数なので、gitignoreを尊重させたいときは false を指定します。指定する値と欲しい挙動が直感と逆になる点に注意してください。

settings.jsonの env キーに書けば、プロジェクトを開くたびに自動で反映されます。

{
  "env": {
    "CLAUDE_CODE_GLOB_NO_IGNORE": "false"
  }
}

シェルの環境変数として一時的に切り替えることもできます。

export CLAUDE_CODE_GLOB_NO_IGNORE=false
claude

env キー経由の配布はプロジェクト共有settingsに書けばチーム全員に同じ挙動を強制でき、シェルのexportは自分のセッションだけに閉じます。settings.jsonの env キーそのものの使い方はClaude Code settings.json完全ガイドで扱っています。

Grepでgitignore対象を検索する方法

Grepには CLAUDE_CODE_GLOB_NO_IGNORE のような専用の切り替えフラグがありません。gitignore対象を常に飛ばす設計です。それでも、対象のファイルパスが分かっていれば検索自体は可能です。

Claudeに「.env.example の中身を検索して」のようにファイルパスを直接伝えると、Grepはそのファイルへ明示的にアクセスします。gitignoreによるフィルタリングは、パターンマッチで候補を広く洗い出すときにだけ働く仕組みだからです。狙ったファイルが最初から分かっている検索では、この制約はほとんど問題になりません。

ターミナルからripgrep自体を直接呼び出せば、gitignoreを無視した全文検索も可能です。Claudeの外で確認したいときに使います。

rg --no-ignore "API_KEY" .

設定を変えても挙動が変わらないときの確認

3つの設定はどれもJSONファイルへの追記だけで完結しますが、反映されない場合はまず置き場所を疑います。respectGitignore と CLAUDE_CODE_GLOB_NO_IGNORE はいずれもManaged / User / Project / Localの4階層で読み込まれ、優先度の高い階層の値が勝ちます。個人設定でfalseにしたつもりでも、プロジェクト共有settingsやmanaged settingsに競合する値が先に置かれていれば、そちらが優先されます。

環境変数の env キーはセッション起動時にまとめて読み込まれる点にも注意します。Claude Codeを起動したまま settings.json の env を書き換えても、その場では反映されません。セッションを再起動して新しい環境変数を読み込ませる必要があります。設定がどの階層で決まっているか分からなくなったときは、Managed → User → Project → Localの順に各settings.jsonファイルを見比べ、同じキーが複数階層に重複していないかを確認します。

VS Code拡張のrespectGitIgnoreは別の設定

紛らわしいことに、VS Code拡張には独立した respectGitIgnore という設定があります(大文字小文字がsettings.jsonのキーと1文字違います)。こちらはCLIの @ メンションではなく、VS Code拡張自体のファイル検索機能に対して働く設定で、既定値は true です。

CLIのsettings.jsonにある respectGitignore を変更しても、VS Code拡張の検索挙動は変わりません。逆にVS Code拡張の設定を変えても、ターミナルで動くClaude Codeの @ 候補には影響しません。同じような名前の設定が2つの製品面に別々に存在すると考えておくと、切り分けで迷いません。

どの設定をいつ使うか

よくある質問

respectGitignoreをfalseにすると何が変わりますか

@ メンションの候補にgitignore対象のファイルも表示されるようになります。secrets系のファイルを誤って添付するリスクが上がるため、常時falseにするより、必要な作業のときだけ一時的に切り替える運用が向いています。

.claudeignoreのような専用の除外ファイルはありますか

CLIには専用のignoreファイルの仕組みはなく、.gitignore の内容をそのまま流用する設計です。除外対象を増やしたいときは .gitignore 自体に追記します。

managed settingsでrespectGitignoreを組織全体に強制できますか

respectGitignore は通常のsettings.jsonキーです。managed settingsに置けば、ユーザー設定やプロジェクト設定からの上書きを防いだ状態で組織全体に配布できます。環境変数を含む設定全体の階層はClaude Code環境変数リファレンスで扱っています。

gitignore対象のファイルを直接読ませることはできますか

できます。Read・Editはパスを渡された時点でそのまま動くため、@ の候補に出ない特定のファイルでも、パスを直接伝えれば読み書きできます。制御が効くのは候補への表示と検索対象への含有だけです。

respectGitignoreはプロジェクトごとに変えられますか

変えられます。<project>/.claude/settings.json に書けばそのプロジェクトのチーム全員に、settings.local.json に書けば自分の環境だけに適用されます。プロジェクトによって @ 候補の見え方を変えたいときはこの階層差を使います。

gitignoreに登録していないファイルも@候補から除外できますか

respectGitignore は .gitignore のパターンだけを参照するため、この設定単体で任意の基準による除外はできません。除外したいファイルを .gitignore 自体に追記すれば、@ 候補とGrepの両方に一貫して反映されます(Globだけは既定のまま残ります)。

まとめ — 3つの設定を混同しない

@ メンション候補は respectGitignore、Globの検索対象は CLAUDE_CODE_GLOB_NO_IGNORE、Grepの検索対象は設定不可という3つの軸を別々に覚えておく必要があります。1つの設定を変えれば全部そろうと考えると、期待通りの除外や検索ができず原因を探し直すことになります。gitignoreにまつわる挙動で迷ったら、まず「候補の話か、Globの話か、Grepの話か」を切り分けるところから始めるのが近道です。

3つとも根っこは .gitignore という同じファイルを見ていますが、参照するかどうかの判断はツールごとに独立しています。設定を1か所に集約する仕組みはありません。監査目的でgitignore対象ファイルの扱いを揃えたい場合は、respectGitignore ・CLAUDE_CODE_GLOB_NO_IGNORE ・Grepの明示パス指定を、それぞれ意識的に運用へ組み込みます。