プロジェクトを進めるうちに、本来バージョン管理すべきでないファイルがリモートリポジトリに紛れ込んでしまった──そんな経験をお持ちのエンジニアの方は少なくないのではないでしょうか。.envファイルやビルド成果物、IDEの設定ファイルなど、一度pushしてしまうと対処に迷うものです。本記事では、Gitのリモートリポジトリから不要なファイルを安全に削除する具体的な手順を、実務での注意点を交えながら解説します。
trackedファイルとuntrackedファイルの違いを正しく理解する
Gitにおけるファイルの状態を正確に把握することが、不要ファイル削除の第一歩です。Gitはリポジトリ内のファイルを大きく「tracked（追跡対象）」と「untracked（未追跡）」の2種類に分類しています。
trackedファイルは、過去にgit addされ、少なくとも一度はコミット履歴に記録されたファイルです。Gitはこのファイルの変更を常に監視しており、差分検出やステージングの対象となります。
一方、untrackedファイルは、ワーキングディレクトリに存在するもののGitの管理下にないファイルです。git statusを実行すると「Untracked files」として表示されるため、見分けること自体は難しくありません。
ここで重要なのは、.gitignoreに記載されたパターンが効力を発揮するのはuntrackedファイルに対してのみという点です。すでにtrackedになっているファイルは、.gitignoreに追記しても無視されません。筆者自身、以前この仕組みを見落としていて、「.gitignoreに書いたのに反映されない」と悩んだ経験があります。同じように戸惑った方も多いのではないでしょうか。
リモートリポジトリから不要ファイルを削除する具体的な手順
不要なファイルをリモートリポジトリから削除するには、いくつかのアプローチがあります。状況に応じて最適な方法を選ぶことが大切です。
方法1：git rmで追跡対象から外しつつファイルを削除する
ローカルにもリモートにもファイルが不要な場合、最もシンプルな方法です。
git rm path/to/unnecessary-file.log git commit -m "不要ファイルを削除" git push origin main
このコマンドを実行すると、ワーキングディレクトリからもファイルが削除されます。ディレクトリごと削除したい場合は-rオプションを付与してください。
方法2：git rm --cachedでリモートからのみ削除する
設定ファイルなど、ローカルには残しておきたいがリモートからは削除したいケースでは、--cachedオプションが有効です。
git rm --cached path/to/config.local git commit -m "追跡対象から除外" git push origin main
--cachedを指定することで、Gitのインデックス（ステージングエリア）からのみファイルが除去され、ローカルのファイルシステム上には残り続けます。実務では、この方法が最も使用頻度が高いと感じています。
ディレクトリ単位で処理する場合は以下のようになります。
git rm --cached -r node_modules/ git commit -m "node_modulesを追跡対象から除外" git push origin main
方法3：複数ファイルを一括で処理する
プロジェクトの途中で.gitignoreを整備した場合、すでにtrackedになっているファイルを一括で追跡対象から外したくなることがあります。
git rm --cached -r . git add . git commit -m ".gitignoreに基づいて追跡対象を再構成" git push origin main
この手順はインデックスを一度クリアしてから再構成するため、.gitignoreの設定が正しく反映されます。ただし、コミット差分が大きくなるため、チーム開発では事前に共有しておくことをお勧めします。振り返ると、筆者がこの手順を初めて試したときは差分の大きさに驚きましたが、実際にはファイルの内容自体は変わらないため、落ち着いて確認すれば問題ないことがわかりました。
.gitignoreとの連携で再発を防止する
不要ファイルの削除は対症療法に過ぎません。根本的な解決策として、.gitignoreを適切に設定し、同じファイルが再びリポジトリに混入しないようにすることが不可欠です。
削除と.gitignoreへの追記は、セットで行うのが鉄則です。
# 1. .gitignoreに追記 echo "*.log" >> .gitignore echo ".env" >> .gitignore # 2. 追跡対象から除外 git rm --cached *.log .env # 3. まとめてコミット git add .gitignore git commit -m "不要ファイルの追跡除外と.gitignoreの更新" git push origin main
プロジェクト初期に.gitignoreを整備しておくことが理想ですが、現実には開発が進んでから気づくケースも少なくありません。GitHubが公開しているgitignoreテンプレート集は言語やフレームワークごとに網羅されており、プロジェクト開始時の参考として非常に有用です。
また、グローバルな.gitignoreを設定しておくと、OS固有のファイル（.DS_StoreやThumbs.dbなど）をすべてのリポジトリで一括して除外できます。
git config --global core.excludesfile ~/.gitignore_global
この設定を入れておくだけで、うっかりコミットしてしまうリスクが大幅に減ると実感しています。
機密情報を含むファイルの削除には特別な注意が必要
一般的な不要ファイルであれば前述の手順で十分ですが、APIキーやパスワードなどの機密情報を含むファイルがリモートに上がってしまった場合は、より慎重な対応が求められます。
git rmによる削除は最新のコミットからファイルを消すだけであり、過去のコミット履歴にはファイルが残り続けるためです。Git履歴を遡れば誰でもそのファイルを閲覧できてしまう点は、見落とされがちなリスクではないでしょうか。
履歴からも完全に除去する必要がある場合は、git filter-branchや、より高速なBFG Repo-Cleanerといったツールの使用を検討してください。
# BFG Repo-Cleanerの使用例 java -jar bfg.jar --delete-files .env git reflog expire --expire=now --all git gc --prune=now --aggressive git push origin --force
ただし、--force pushはリモートの履歴を書き換えるため、チームメンバー全員への周知が必須です。また、一度でもリモートに公開された機密情報は漏洩した前提で対処するのがセキュリティの原則です。該当するキーやパスワードのローテーション（無効化と再発行）を必ず実施してください。一概にツールだけで解決できる問題ではない部分もあります。
まとめ：日常的な運用に組み込むことが最善の対策
Gitのリモートリポジトリから不要ファイルを削除する方法を整理すると、以下のポイントに集約されます。
- ローカルにも不要 →
git rmで完全削除 - ローカルには残したい →
git rm --cachedで追跡のみ解除 - 再発防止 →
.gitignoreへの追記を必ずセットで実施 - 機密情報 → 履歴からの完全除去とキーのローテーションが必要
最も効果的なのは、プロジェクト初期の.gitignore整備と、コミット前のgit status確認を習慣化することです。問題が起きてから対処するよりも、未然に防ぐ仕組みを日常のワークフローに組み込むほうが、結果として効率的だと感じています。
Git運用やプロジェクトの開発体制に課題を感じていらっしゃる場合は、ぜひaduceのお問い合わせはこちらからお気軽にご相談ください。技術的な課題に対して、チームの状況に合わせた最適な解決策をご提案いたします。