[解決]globalの .gitignore が効かないときのチェックポイント

2025年4月22日 2025年4月22日

ウェブ系ウシジマくん

git-logo

globalのgitignoreを設定する際、記述内容が原因で軽くハマりました。本記事ではその仕組みと解決フローを、コピペ OK のコマンド付きで解説します。

この記事でわかること

global .gitignore とローカル .gitignore の違い
core.excludesFile の設定方法
追跡済みファイルを履歴から外す安全な手順
正しい ignore パターンの書き方（絶対パス・チルダ付きパスは NG）
git check-ignore を使ったデバッグ方法
チーム開発でのベストプラクティスとよくある落とし穴

動作環境の前提条件

項目	バージョン例
Git	2.34 以上
OS	macOS / Linux / Windows いずれも可
シェル	bash / zsh / PowerShell ほか

TIPS

バージョンは git --version で確認できます。

global .gitignore とローカル .gitignore の違い

Git には 「ユーザー全体で有効な ignore ルール」 と 「リポジトリ固有の ignore ルール」 の 2 層があります。前者が global .gitignore（個人環境のゴミ掃除役）、後者が ローカル .gitignore（プロジェクト共有ファイルの管理役）です。

どちらを使うかで適用範囲や優先順位が変わるため、まずは両者の違いを把握することがトラブル回避の第一歩になります。以下の表でポイントを整理しましょう。

項目	global .gitignore	ローカル .gitignore
配置場所	任意パス（例: `~/.config/git/ignore`）を `git config --global core.excludesFile` で登録	リポジトリ直下の `.gitignore`（または各サブディレクトリ）
適用範囲	そのユーザーの全リポジトリ	当該リポジトリのみ
共有方法	コミットされない → 個人設定	リポジトリにコミット → チーム全員で共有
主な用途	IDE キャッシュや OS 依存ファイルなど“個人環境特有”のゴミを除外	ビルド成果物・ライブラリなど“プロジェクト依存”の生成物を除外
優先順位	低い（後述のローカル設定で上書き可）	高い（global ルールより優先される）

覚えておくと便利

.git/info/exclude という“リポジトリローカル & 非コミット”な ignore もある（ニッチだが一時的に便利）。
パターン解決順は「システム → グローバル → .git/info/exclude → 各ディレクトリの ****.gitignore」の順。下位が上位を上書きする。
~/.gitignore_global など好みの名前で OK。core.excludesFile は 1 つしか参照しないので、複数ファイルを合成したい場合はシンボリックリンクや include ディレクティブではなく「1 ファイルにまとめる」方式が無難です。

`core.excludesFile` の設定方法

Ignore ファイルを作成

mkdir -p ~/.config/git
cat <<'EOF' > ~/.config/git/ignore
# IDE 設定
.idea/

# macOS の不要ファイル
.DS_Store
EOF

Git に登録

git config --global core.excludesFile ~/.config/git/ignore
# 設定確認
git config --global --get core.excludesFile

これで 全リポジトリ に .idea/ と .DS_Store を無視するルールが適用されます。

シェル別の注意点

PowerShell では echo "..." > $HOME/.config/git/ignore などパス表記を変える
Windows 環境で ~ が認識しにくい場合はフルパスを書いておくと吉。

追跡済みファイルを履歴から外す安全な手順

.gitignore は 未追跡 (untracked) ファイルにしか効かない ため、すでにコミット済みのゴミを除外するには「履歴から外して保持する」操作が必要です。

手順

# 例) IDE 設定ディレクトリを履歴から外す
git rm --cached -r .idea

# 例) macOS キャッシュを一括で外す
find . -name '.DS_Store' -print0 | xargs -0 git rm --cached --ignore-unmatch

git commit -m "Stop tracking IDE & macOS cache files"

--cached を付けることで ワークツリーには残しつつリポジトリだけから削除 できます。
大量に対象がある場合は git ls-files -i --exclude-standard で一覧化 → まとめて rm するワンライナーが便利。

代替案

git update-index --skip-worktree <path> でも履歴を残したまま変更検知を止められますが、一時的なケース向けです。

正しい ignore パターンの書き方（絶対パス・チルダ付きパスは NG）

パターンの評価順は「上から下」。同じファイルに複数マッチする場合は最後のルールが勝つ、後勝ち方式です。ですので、例外的に追跡したい場合は !重要.log のように ! で除外解除しましょう。また、Windows では Thumbs.db、Linux では *~ や *.swp なども追加すると吉です。

記述例	有効?	解説
`.idea/`	✅	どの階層でも `.idea` ディレクトリを無視
`/.idea/`	✅	ルート直下限定。サブディレクトリの `.idea` は対象外
`~/RubymineProjects/.../.idea/`	❌	`~`・絶対パスは評価対象外。リポジトリ相対で書く必要あり
`*.log`	✅	任意階層の拡張子 `.log` を無視
`build/`	✅	ビルド成果物ディレクトリ

`git check-ignore` を使ったデバッグ方法

git check-ignore は どの ignore ルールがヒットしたか を教えてくれる強力な診断コマンドです。

# ファイルが無視されているか＆理由を調べる
git check-ignore -v .idea/workspace.xml

出力例:

~/.config/git/ignore:3:.idea/        .idea/workspace.xml

左から「ignore ファイルのパス:行番号:パターン → 対象ファイル」の形式。
ディレクトリ全体を調べるなら git ls-files -io --exclude-standard | git check-ignore -v --stdin も便利です。

チーム開発でのベストプラクティスとよくある落とし穴

ベストプラクティス

共有と個人を分離
- プロジェクト共有 → .gitignore にコミット
- 個人設定 → global .gitignore に記載
IDE／OS 別テンプレートを活用
- github/gitignore レポジトリのサンプルが充実。
CI でチェック
- git ls-files -z | xargs -0 grep -Il "^<<<<<<<" などを使い、不要ファイルの混入を防ぐ。
ドキュメント化
- Why を README / Wiki に残すことで「なぜ除外しているか」が共有できる。

よくある落とし穴

症状	原因	対策
global ignore が効かない	`core.excludesFile` のパスミス	`git config --global --get core.excludesFile` で確認
`.gitignore` に書いても `git status` に出る	すでに追跡済み	`git rm --cached` で履歴から外す
絶対パス・`~` が効かない	パターン仕様を誤解	必ずリポジトリ相対で書く
誰かが違う IDE を使っていてゴミが増える	共有 ignore に欠落	チームで IDE 別テンプレートを相談して追記