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

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

しかも既定の向きが揃っていません。@ 候補とGrepはgitignore対象を外し、Globは含めます。この記事は「どのツールの結果が、どの設定で変わるのか」を症状から逆引きできるように組んでいます。

まず3つの仕組みの違いを押さえる

同じ「ファイルを探す」動作でも、@ 候補・Glob・Grepはそれぞれ別の仕組みで動き、gitignoreの扱いも別々に決まっています。

Globは **/*.js のような名前のパターンで、Grepはファイルの中身の文字列で探します。公式のツールリファレンスは、Globを「既定ではgitignoreを尊重しない」、Grepを「gitignoreを尊重するのでgitignore対象は飛ばす」と区別して書いています。

@候補の出方を変える — respectGitignore

respectGitignore は、@ を押したときのファイル候補から .gitignore に一致するものを外すかどうかを決めます。型は真偽値で、既定は true です。node_modules やビルド成果物は、この既定のままなら候補に出ません。

{
  "respectGitignore": false
}

false にすると、gitignore対象も候補に並びます。ローカル専用の設定ファイルやビルド出力を @ で渡したいときに使えます。秘密情報を置いたファイルまで候補に出る点は意識しておく必要があります。

このキーはv2.1.0で追加されました。settings.json以外に、/config の「Respect .gitignore in file picker」でも切り替えられます。こちらは ~/.claude.json に書き込まれます。

settings系のどのファイルにもキーが無いときだけ、Claude Codeは ~/.claude.json の値を使います。/config で切り替えたはずなのに効かないときは、プロジェクト側のsettings.jsonに別の値が書かれていないかを疑います。階層の優先順位はClaude Code設定ガイドで扱っています。

settings.local.json はClaude Codeが書き込むときにgitignore対象として扱われます。その仕組みはgitignoreされる仕組みに詳しい解説があります。

候補の探し方そのものを差し替えるfileSuggestion

候補の出し方を変える手段は、もう1つあります。v2.0.65で追加された fileSuggestion は、@ の候補を自前のコマンドで供給させる設定です。

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

コマンドには、入力中の文字列が query というフィールドのJSONで標準入力に渡されます。コマンドは5秒を超えると待たれなくなります。大きなモノレポで、事前に作った索引から候補を返したい場合に向く機能です。

コマンドはファイルパスを改行区切りで標準出力に返します。表示されるのは最大15件です。信頼していないフォルダでは実行されず、組み込みの候補に戻ります。

この設定を使うと、respectGitignore が候補にどう作用するかは公式に書かれていません。自前コマンドを使うなら、gitignoreの扱いはコマンド側で決めると考えるのが安全です。

GlobとGrepで挙動が逆になる理由を実測する

公式の説明を読むだけでは、「Globがgitignoreを無視する」ことの意味がつかみにくいものです。Grepはripgrepがベースのツールなのでripgrepで同じ条件を再現すると、Grepの側は手元で確認できます。次のディレクトリで試しました。

git init -q && printf '.env\nnode_modules/\n' > .gitignore
echo 'API_KEY=abc' > .env
mkdir node_modules && echo 'API_KEY=zzz' > node_modules/x.js
echo 'API_KEY=ex' > app.js
rg -l API_KEY .
rg -l --no-ignore API_KEY .
rg -l API_KEY .env

v2.1.287同梱のripgrepで、出力は次のとおりでした。

./app.js
./node_modules/x.js
./app.js
.env

1つ目の既定の検索では、gitignore対象の .env と node_modules/x.js が飛ばされ、app.js だけが残ります。--no-ignore を付けると node_modules/x.js が現れました。3つ目のようにパスを直接渡すと、gitignore対象でも検索されます。.env は --no-ignore の結果に出ていませんが、これはripgrepが隠しファイルを既定で除く(--hidden で含められる)ためで、gitignoreとは別の動きです。

Grepで .env の中身を探したいときは、ツールのリファレンスにあるとおり、Claudeにパスを直接伝えます。Globは逆で、名前のパターンが一致すればgitignore対象も返します。

Globにはもう1つ、隠しファイルの扱いという軸があります。.env のようなドットファイルも、Globは既定で結果に含めます。外したいときは環境変数 CLAUDE_CODE_GLOB_HIDDEN に false を入れます。この変数も @ 候補とGrepには影響しません。

Globをgitignore対応にするCLAUDE_CODE_GLOB_NO_IGNORE

Globにもgitignoreを守らせたい場合は、環境変数 CLAUDE_CODE_GLOB_NO_IGNORE に false を入れて起動します。変数名は「無視しない」の意味なので、守らせたいときの値が false になります。直感と逆なので間違えやすい点です。

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

シェルから一時的に切り替えるなら、次のように起動します。ツールリファレンスは「Claude Codeを起動する前に設定する」と書いています。

export CLAUDE_CODE_GLOB_NO_IGNORE=false
claude

この変数は @ のオートコンプリートには影響しません。@ 側は respectGitignore だけが担当します。env キーの使い方はClaude Code settings.json完全ガイドで、環境変数の全体像は環境変数リファレンスで扱っています。

gitignoreは「読ませない」ための設定ではない

ここまでの3つは、検索や候補を絞るための設定です。ファイルを読ませない境界にはなりません。公式のGrepの説明にも、gitignore対象のファイルはパスを直接渡せば検索できる、とあります。

読み取りを止めたいときは、権限ルールのほうを使います。permissions.deny に Read(./.env) のようなルールを書く形です。ReadとEditのルールは、gitignoreと同じパターン構文で書けます。

{
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

なお、プロジェクトに .claudeignore というファイルを置いても効果はありません。中身は Read の拒否ルールへ移します。

つまりgitignoreと権限ルールは、パターンの書き方こそ似ていますが、役割が別です。.gitignore は「結果に混ぜないための絞り込み」、deny は「そのパスへのアクセスを止める」ための仕組みです。秘密情報の扱いで迷ったら、respectGitignore ではなく権限ルールの側を見ます。

設定を変えても挙動が変わらないときの切り分け

症状ごとに、疑う場所の順番は決まっています。

3つ目は特に見落としやすい点です。CLAUDE_CODE_GLOB_NO_IGNORE はClaude Codeの起動前に設定する決まりなので、起動済みのセッションで書き換えても反映を期待できません。再起動して確かめます。

どの階層の値が効いているのか分からないときは、読み込む設定を絞って起動する手もあります。v2.1.287の claude --help には、--setting-sources が載っています。

claude --setting-sources user

user・project・local をカンマ区切りで指定すると、その階層の設定だけを読み込みます。上のコマンドならプロジェクトとローカルのsettingsを外せるので、プロジェクト側の値が効いていたかどうかを切り分けられます。同じ --help に、gitignoreを直接扱うフラグはありませんでした。

Glob・Grep・@ 候補の挙動は、バージョンによっても変わってきました。たとえばv2.1.76では、VS Code拡張で、カンマを含むgitignoreのパターンが @ 候補からファイル種別をまるごと除外してしまう不具合が直っています。候補の欠け方が不自然なときは、バージョンも確かめてください。

VS Code拡張のrespectGitIgnoreは別の設定

VS Code拡張には、respectGitIgnore(大文字のIが1文字違い)という独立した設定があります。既定は true で、公式の拡張機能設定の表には「ファイル検索と選択範囲のコンテキストから.gitignoreのパターンを除外する」と書かれています。

CLIのsettings.jsonにある respectGitignore を変えても、拡張機能設定は変わりません。逆も同じです。名前が1文字違いなので、どちらの設定を触っているかを毎回確かめます。

拡張機能側には、@ 候補とは別の動きもあります。ワークスペース内の、gitignore対象のファイルで選択したテキストについて、Claudeに渡るのは多くてもパスだけです。条件は、VS Codeの search.useIgnoreFiles と拡張の respectGitIgnore の両方がオンの場合で、どちらも既定でオンです。

この絞り込みはチャットパネルだけに効き、統合ターミナルで動くCLIには効きません。ターミナル側では選択したテキストがファイルを問わず送られるため、守りたいファイルには前述の Read の拒否ルールを置きます。

どの設定をいつ使うか

Globの既定のまま使うなら、ビルド成果物やログも名前で拾えます。この場合は何も変える必要がありません。

まとめ

@ 候補・Glob・Grepの3つは、gitignoreの扱いがそれぞれ独立しています。結果が思った通りにならないときは、設定を変える前に「候補の話か、Globの話か、Grepの話か」を決めるのが最短です。

gitignoreは読み取りを止める仕組みではないので、機密ファイルの保護には向きません。守りたいなら権限ルール、見え方を整えたいなら respectGitignore と CLAUDE_CODE_GLOB_NO_IGNORE、と目的で道具を分けます。Claude Codeの設定全体を見直すときも、この分け方が使えます。