settings.local.jsonがgitignoreなしで除外される仕組み — Claude Code
settings.local.jsonは初回書き込み時にグローバルgit excludesへ自動追記され、gitignore編集なしでコミット対象から外れます。手動作成やworktree・Windowsでの例外条件も扱います。
.claude/settings.local.json はプロジェクトごとの個人設定を置くファイルですが、.gitignore に自分で書かなくてもコミット対象から外れます。Claude Codeが初めてこのファイルへ書き込むタイミングで、グローバルなgit excludesファイルへパターンを自動追記するためです。仕組みが効くのは「Claude Codeが書いた場合」だけで、手動で作った直後はこの保護が働きません。
settings.local.jsonがgitignore不要で除外される理由
Claude Codeは、Bashコマンドの許可プロンプトで「Yes, and don't ask again」を選ぶと、その承認を allow ルールとして .claude/settings.local.json に保存します。書き込みが初めて発生した時点で、まだそのリポジトリがこのファイルを無視していなければ、Claude Codeは **/.claude/settings.local.json というパターンをグローバルなgit excludesファイルに追記します。
この追記は1回限りではありません。ファイルを無視していないリポジトリで書き込みが発生するたびに確認し、必要ならそのつど追記します。結果として、これから作る新しいリポジトリを含め、以後すべてのリポジトリで .claude/settings.local.json がコミット対象から外れます。プロジェクトの .gitignore を編集する必要は一度もありません。
git管理下のプロジェクトでこの設定ファイルを使う人にとっては、.gitignore への追記を毎回のプロジェクトセットアップ手順から省ける効果があります。個人ごとの許可ルールやテーマ設定を .claude/settings.local.json に集める設計自体はClaude Code settings.json完全ガイドで扱っていますが、その「git管理外」がどう成立しているかの内部動作はあまり知られていません。
.claude/settings.json は「コミットすればチーム全員に届く」設定で、.claude/settings.local.json は最初から「自分のこの1プロジェクトだけ」に閉じたスコープを持ちます。チーム共有ファイルにコミットするかどうかは書き手の判断に委ねられますが、個人スコープのファイルは性質上コミットされるべきではありません。この非対称な性質の違いが、後者だけを自動でgit管理外に置く設計の前提になっています。
グローバルgit excludesへの追記先はどこか
自動追記の宛先は、個人のgit設定によって2通りに分かれます。判定はシンプルで、core.excludesFile を絶対パスか ~ から始まるパスで設定しているかどうかだけです。
| git設定の状態 | 追記先 |
|---|---|
core.excludesFile を絶対パスまたは ~/... で設定済み | 追記先そのファイル |
core.excludesFile 未設定・XDG_CONFIG_HOME 設定あり | 追記先$XDG_CONFIG_HOME/git/ignore |
| どちらも未設定 | 追記先~/.config/git/ignore |
core.excludesFile はリポジトリ単位の .gitignore と違い、そのマシン上のすべてのgitリポジトリに効くグローバル設定です。Claude Codeが追記するのはこの1ファイルだけなので、複数のプロジェクトを横断してもパターンを重複登録する必要がありません。逆に言えば、既に core.excludesFile を設定してあるチームや個人ほど、Claude Codeの追記先を正確に特定できます。設定していない場合は ~/.config/git/ignore を見ればパターンの有無を確認できます。
手動作成したときだけ自分でgitignoreが要る
自動追記が効くのは、あくまで「Claude Codeが最初にこのファイルへ書き込んだとき」です。先に自分で .claude/settings.local.json を手で作成し、Claude Codeがまだ一度も書き込んでいない場合、この保護は発動しません。手で作ったファイルを .gitignore に自分で追記しないままにすると、そのままコミットされてしまいます。
つまずきやすい具体的な状況は次の2つです。
- チームのテンプレートから
.claude/settings.local.jsonの雛形をコピーした場合: Claude Code自身がまだ書き込んでいないため、自動追記は起きません。コピーした時点で.gitignoreへの追記を自分で行う必要があります。 - 既存のリポジトリに後からClaude Codeを導入した場合: 最初の許可プロンプトでファイルが作られるまでの間、リポジトリはこのファイルを無視していません。導入直後に何らかの理由でファイルが手動で先に作られていると、同じ抜け穴が起こります。
自動追記が発生済みかどうかは、無視パターンが効いているかで切り分けられます。
git check-ignore -v .claude/settings.local.jsonパターン一致行(core.excludesFile またはグローバル git/ignore のパスと **/.claude/settings.local.json)が出力されれば、自動追記は既に完了しています。何も出力されなければ、そのファイルはまだ無視されておらず、git status で Untracked files に表示された時点でコミット候補に入り得る状態です。手で作成した直後や、既存プロジェクトへの導入直後はこのコマンドで先に確認しておくと安全です。
worktreeとリポジトリルートでの配置ルール
Claude Codeは .claude/settings.local.json を、セッションを開始したディレクトリではなくgitリポジトリのルートで読み書きします。サブディレクトリで作業していても、承認ルールはリポジトリ全体に適用されます。worktreeの場合はさらに一段階挟み、worktreeごとのルートではなくメインチェックアウトのルートにあるファイルを使います。複数のworktreeを並行して使っていても、許可ルールは1か所に集約される設計です。
このルート集約には例外もあります。リポジトリの外で使っている場合、リポジトリルートがホームディレクトリと一致する場合、Windows環境の場合、あるいはリポジトリルートや .git / .claude エントリが自分のユーザー所有になっていない場合は、ファイルは通常どおり .claude/settings.json と同じ場所に置かれます。加えて、パーミッションルールの中で / から始まるパスや相対的なサンドボックスパスは、リポジトリルートではなくセッションの作業ディレクトリを基準に解決される点も、ルート集約とは別の注意点です。
v2.1.211より前のバージョンでは、Claude Codeはこのファイルをセッション開始ディレクトリに置いていました。現在のバージョンでも、その旧位置に残されたファイルは読み込み対象になり、両方のファイルが同じキーを設定していればリポジトリルート側の値が優先されます。Agent SDKの resolveSettings() ヘルパーはこの集約に関わらず、常にセッション開始ディレクトリからファイルを読みます。
Windows環境や CLAUDE_CONFIG_DIR でホームディレクトリの置き場所を変えている場合、~/.claude の意味そのものが変わります。Windowsでは ~/.claude は %USERPROFILE%\.claude を指し、CLAUDE_CONFIG_DIR を設定していれば設定・セッション履歴・プラグインはそのディレクトリに移ります。このディレクトリがgitリポジトリの中にある場合、.claude/settings.local.json の置き場所とgit excludesへの追記対象パスも、通常のホームディレクトリ運用とは変わってきます。
追跡済みになるとworkspace trustの扱いが変わる
自動でのgitignore化と対になっているのが、workspace trustとの関係です。.claude/settings.local.json は本来「自分のためだけのファイル」なので、Claude Codeはこのファイルの allow ルールを、コミット済みの .claude/settings.json に必須のworkspace trustのステップなしで適用します。
ただしこの扱いは、ファイルがgit管理外の状態に限られます。ファイルがgitで追跡されている場合、または .claude ディレクトリ自体がシンボリックリンクになっている場合、Claude Codeはこのファイルをリポジトリ側が供給したものとみなし、通常のプロジェクト設定と同じくworkspace trustを通すまでルールを保留します。「手動作成 + 追跡開始」の組み合わせは、gitignore漏れと信頼ステップの両方に同時に影響する点で、特に見落としやすいケースです。
Claude Codeがこの追跡有無をgitで確認できるのは、フォルダを信頼した後だけです。フォルダを信頼する前は、自分のホームディレクトリ(または CLAUDE_CONFIG_DIR で設定した設定ホーム)であればgitを実行せずそのままルールを適用し、それ以外の場所ではプロジェクト設定と同じ扱いでルールを保留します。
フォルダをまだ信頼していない状態にも2種類あり、permissions.allow ルールの扱いが変わります。
| 未信頼の状況 | permissions.allow ルールの扱い |
|---|---|
| 親ディレクトリだけ信頼済み | permissions.allow ルールの扱い適用されない。信頼ダイアログが再度表示され、ルール一覧を確認してから承諾すると適用される |
claude -p またはSDKでフォルダ自体が未信頼 | permissions.allow ルールの扱い適用されない。ダイアログは出ず、this workspace has not been trusted という警告が標準エラー出力に表示される |
「保存したはずの許可ルールが効かない」と感じたら、この2つのどちらに当てはまるかをまず確認します。前者はダイアログを承諾すれば解消し、後者は -p やSDKからの実行である限り毎回警告が出ます。この保留と再適用の境目、そして許可プロンプトが繰り返し出る原因の全体像はClaude Code権限モデルの変遷で扱っています。
この自動化はどこまで信用してよいか
個人設定は必ずgit管理外にするという設計方針を、手作業の追記漏れという典型的な事故から守る仕組みです。効果が及ぶ範囲は前節で見た条件に限られるため、チーム展開の場面では過信すると危険が残ります。オンボーディング手順に「.claude/settings.local.json のひな形をコピーしてください」という一文があると、そのコピー先ではClaude Codeの自動追記がまだ動いていないため、無防備な状態でファイルが残ります。個人設定のテンプレートを配るなら、コピー先で .gitignore への追記もセットで案内しておくのが安全です。
許可ルールが蓄積した .claude/settings.local.json がそのままコミットされると、単なる設定ファイルの重複以上の問題が起きます。allow ルールにはコマンドのプレフィックスやファイルパスのパターンが並ぶため、社内ツールの名前やローカルの絶対パスなど、公開したくない情報がチーム共有リポジトリに残ることがあります。自動追記が効いていれば起きない事故ですが、テンプレートのコピーのように自動追記が働かない経路では、この種の情報漏えいリスクも含めて注意する価値があります。
まとめ
.claude/settings.local.json がgitignoreなしで除外されるのは、Claude Codeが初めて書き込んだ時点でグローバルなgit excludesへ **/.claude/settings.local.json を自動追記するためです。追記先は core.excludesFile の設定有無で変わり、手動で先にファイルを作った場合はこの保護が働かないので自分で .gitignore に追記する必要があります。worktreeではメインチェックアウトのルートに集約され、ファイルがgitで追跡され始めるとworkspace trustの扱いも通常のプロジェクト設定に戻ります。個人設定を配布するときは、この自動化が「Claude Codeが書いた場合」に限定される前提を忘れずに扱うと安全です。