目次
.gitignoreを後から追加してgit管理から除外したいケースは開発中によく発生する。すでにリポジトリに追加されているファイルやディレクトリを管理対象から外すには、単に.gitignoreに記述するだけでは不十分である。本記事では、git rm --cachedコマンドを使った確実な除外方法を5ステップで解説する。
この記事で分かること
- .gitignore後から追加しても除外されない理由
git rm --cachedの正しい使い方- ファイル・ディレクトリ別の実践手順
- よくあるエラーと対処法
対象読者: Git初心者〜中級者
動作確認環境: Git 2.30以降、Windows 10/11、macOS、Linux（2025年10月時点）
.gitignoreを後から追加しても除外されない理由
.gitignoreファイルは、未追跡（untracked）ファイルのみを対象とする。すでにGitリポジトリに登録されているファイルは、.gitignoreに記述しても管理対象から除外されない。
Gitの追跡状態の分類
状態 | 説明 | .gitignoreの効果 |
|---|---|---|
未追跡（Untracked） | 一度もgit addされていない | ✅ 有効 |
追跡済み（Tracked） | すでにリポジトリに登録済み | ❌ 無効 |
ステージング（Staged） | git addされたがコミット前 | ❌ 無効 |
なぜこの仕様なのか
Gitは「一度追跡したファイルは、明示的に除外しない限り追跡し続ける」という設計思想を持つ。これにより、誤って.gitignoreに記述してもファイルが失われるリスクを防いでいる。
後から除外する5ステップの手順
ステップ1: .gitignoreファイルを作成・編集
プロジェクトルートに.gitignoreが存在しない場合は作成する。
touch .gitignore
除外したいファイル・ディレクトリを記述する。
.gitignore の例:
# 開発環境設定
.vscode/
.idea/
# 環境変数ファイル
.env
.env.local
# ビルド成果物
dist/
build/
*.log
ステップ2: 現在の追跡状態を確認
どのファイルが追跡されているか確認する。
git ls-files
除外したいファイルが一覧に含まれていれば、次のステップで削除が必要である。
ステップ3: ディレクトリを管理対象から除外
ディレクトリごと除外する場合は-rオプションを付ける。
git rm --cached -r .vscode/
オプションの意味:
--cached: リポジトリの追跡のみ解除（ローカルファイルは削除しない）-r: 再帰的にディレクトリ内すべてを対象
ステップ4: ファイルを管理対象から除外
単一ファイルを除外する場合は-rオプションは不要。
git rm --cached .env
複数ファイルを一括除外:
git rm --cached *.log
ステップ5: 変更をコミット
除外設定と管理対象からの削除をコミットする。
git add .gitignore
git commit -m "不要なファイルをgit管理対象から除外"
コミット後、リモートにプッシュすれば完了である。
git push origin main
実践例：よくある除外パターン
パターン1: .vscodeディレクトリを除外
# .gitignoreに追加
echo ".vscode/" >> .gitignore
# 管理対象から除外
git rm --cached -r .vscode/
# コミット
git add .gitignore
git commit -m ".vscodeをgit管理から除外"
パターン2: 環境変数ファイルを除外
# .gitignoreに追加
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
# 管理対象から除外
git rm --cached .env .env.local
# コミット
git add .gitignore
git commit -m "環境変数ファイルを除外"
パターン3: node_modulesを除外（後から）
# .gitignoreに追加
echo "node_modules/" >> .gitignore
# 管理対象から除外
git rm --cached -r node_modules/
# コミット
git add .gitignore
git commit -m "node_modulesを除外"
よくあるエラーと対処法
エラー1: fatal: pathspec 'xxx' did not match any files
原因: 指定したファイル・ディレクトリが存在しないか、すでに追跡されていない。
対処法:
# 追跡状態を確認
git ls-files | grep xxx
# ファイルが存在するか確認
ls -la xxx
エラー2: ローカルファイルが削除された
原因: --cachedオプションを付け忘れた。
対処法:
# コミット前なら元に戻せる
git reset HEAD
# コミット後なら前のコミットに戻す
git reset --hard HEAD^
# ファイルを復元
git checkout HEAD -- ファイル名
エラー3: .gitignoreが効かない（キャッシュ問題）
原因: Gitのインデックスキャッシュが残っている。
対処法:
# 全ファイルのキャッシュをクリア
git rm -r --cached .
# 再度追加（.gitignoreが適用される）
git add .
# コミット
git commit -m "gitignoreを適用"
チーム開発での注意点
既存メンバーへの影響
git rm --cachedを実行してプッシュすると、他のメンバーがgit pullしたときにローカルファイルが削除される場合がある。
推奨手順:
- チームに事前通知
- メンバーに重要ファイルのバックアップを依頼
- プルリクエストで変更内容を明示
.gitignore_globalの活用
個人の環境設定は、グローバル設定で除外すると便利である。
# グローバル.gitignoreを作成
touch ~/.gitignore_global
# Gitに設定
git config --global core.excludesfile ~/.gitignore_global
~/.gitignore_global の例:
# エディタ設定
.vscode/
.idea/
# OS固有ファイル
.DS_Store
Thumbs.db
よくある質問（FAQ）
Q1: git rm --cachedとgit rmの違いは?
A: --cachedオプションの有無で動作が異なる。
コマンド | リポジトリ | ローカルファイル |
|---|---|---|
| 削除 | 保持 |
| 削除 | 削除 |
開発中のファイルを残したい場合は、必ず--cachedを使用する。
Q2: すでにプッシュ済みのファイルを除外できる?
A: できる。ただし、リモートリポジトリから削除される点に注意が必要である。
git rm --cached ファイル名
git commit -m "ファイルを除外"
git push origin main
他のメンバーがgit pullすると、そのファイルは削除される。事前にチームへ周知すること。
Q3: .gitignoreに追加したのに反映されない
A: 以下の原因が考えられる。
- すでに追跡済み →
git rm --cachedで除外 - 記述ミス → パスの記述方法を確認
- キャッシュ残存 →
git rm -r --cached .で全クリア
Q4: ディレクトリ内の特定ファイルだけ残したい
A: .gitignoreで除外後、例外を!で指定する。
# logsディレクトリ全体を除外
logs/
# .gitkeepだけ追跡
!logs/.gitkeep
Q5: 間違えてファイルを削除してしまった
A: コミット前ならgit resetで復元できる。
# ステージングを取り消し
git reset HEAD ファイル名
# ファイルを復元
git checkout -- ファイル名
コミット後ならgit revertまたはgit reset --hardを使用する。
まとめ
.gitignoreを後から追加してgit管理から除外するには、以下の手順が必要である。
- .gitignoreに除外パターンを記述
git rm --cachedで追跡を解除- 変更をコミット・プッシュ
重要ポイント:
--cachedオプションを必ず付ける（ローカルファイルを保持）- チーム開発では事前周知が必須
- 個人設定は
.gitignore_globalを活用
この手順を覚えておけば、環境設定ファイルやビルド成果物を後から安全に除外できる。