大容量ファイルを含むリポジトリの管理方法

このドキュメントでは、GitHub Desktop を使用してリポジトリを管理する際に、大容量ファイル(100MB 超)を扱う際の注意点と対処方法について説明します。スクリーンショットにある状況を例に、具体的な手順や推奨される方法をまとめています。


1. 背景と問題点

GitHub では、リポジトリに直接プッシュできるファイルのサイズに制限があります。

  • 100MB を超えるファイル: GitHub にプッシュできません。
  • 50MB を超えるファイル: プッシュは可能ですが、警告が表示されます。

スクリーンショットに示されている通り、以下のような警告ダイアログが GitHub Desktop 上で表示されます。

Files too large
The following files are over 100MB. If you commit these files, you will no longer be able to push this repository to GitHub.com …

このように 100MB を超えるファイルが含まれている場合、通常のリポジトリではプッシュに失敗し、GitHub にアップロードできなくなります。


2. 大容量ファイルを扱うときの選択肢

大容量ファイルがリポジトリに含まれる場合、以下のような対処方法が考えられます。

  1. Git LFS (Large File Storage) を利用する
    • GitHub が提供している大容量ファイル管理機能です。
    • 100MB を超えるファイルや画像、動画、バイナリデータを Git LFS で管理することで、リポジトリ本体(Git データ)にはファイルの参照情報のみを含めることができます。
    • GitHub 上のリポジトリでは大容量ファイルの実データを別サーバーに置き、差分管理もしやすくなります。
  2. ファイルをコミットしない (リポジトリに含めない)
    • プロジェクトでどうしても不要であれば、.gitignore で除外してコミットしない。
    • 必要であっても、リポジトリで管理する必要がなければ別のストレージサービス(例: Google Drive、Dropbox など)で共有する。
  3. ファイルを分割・圧縮する
    • 100MB を超えないようにファイルを分割・圧縮するという手もあります。
    • ただし、バイナリファイル(画像や動画)を圧縮しても容量がほとんど変わらない場合があります。
    • 運用の複雑さを考えると、Git LFS を利用する方がスムーズです。

3. Git LFS の導入手順(GitHub Desktop を例に)

ここでは、最も一般的な解決策である Git LFS の導入 手順を簡単にまとめます。

  1. Git LFS のインストール
    • 公式サイト( https://git-lfs.github.com/ )からダウンロードし、インストールします。
    • macOS や Linux の場合はパッケージマネージャ経由でもインストール可能です(例: Homebrew など)。
  2. リポジトリに Git LFS を初期化
    • ターミナルを開き、該当のリポジトリのフォルダへ移動します。
    • 以下のコマンドを実行して Git LFS を初期化します。
      bash git lfs install
    • (必要に応じて)以下のように特定のファイル形式を LFS で管理するよう設定します。
    • bash git lfs track "*.png" git lfs track "*.psd" git lfs track "*.mp4"
    • これらの設定が .gitattributes ファイルに追記されます。
  3. GitHub Desktop でコミット & プッシュ
    • Git LFS でトラッキング対象に設定したファイルを追加・コミットします。
    • GitHub Desktop 上でプッシュを実行すると、対象のファイルは自動的に Git LFS にアップロードされます。
    • もし「Files too large」のエラーが出る場合は、一度コミットを取り消して再度 Git LFS の設定を行った後にコミットし直してください。

4. .gitignore によるファイルの除外

大容量ファイルをリポジトリで管理しない方針の場合は、.gitignore ファイルを使ってコミット対象から除外 することができます。GitHub Desktop のメニューでは、下記のような操作が可能です。

  1. 対象ファイルを右クリック
    • GitHub Desktop の「Changes」タブでコミットしたくないファイルを右クリックします。
    • メニューから「Ignore file」あるいは「Ignore … (add to .gitignore)」を選択します。
  2. .gitignore ファイルが更新される
    • .gitignore ファイルにファイル名やパターンが追記され、以後はそのファイルがコミット対象に含まれなくなります。
  3. 既にコミット済みのファイルは削除が必要
    • もし既にコミットされてしまっている場合は、過去のコミットから削除する作業(git rm --cached ファイル名)が必要です。
    • GitHub Desktop では、コミット履歴を遡ってファイルを削除する操作は基本的にコマンドラインが必要になるため注意してください。

5. 運用上の注意点

  1. 大容量ファイルの扱い方針をプロジェクト開始時に決める
    • ゲーム開発や映像関連プロジェクトなどでは、早めに Git LFS の導入を検討しておくと運用がスムーズになります。
    • 後から Git LFS を導入すると、既にコミットされている大容量ファイルをどう扱うかで手間が増えることがあります。
  2. 誤ってコミットした大容量ファイルをリポジトリから削除するには
    • コミット履歴からファイルを削除する必要があるため、git filter-branchgit filter-repo などのツールを使う場合があります。
    • リポジトリを一度クリーンアップして再アップロードし直す方法もありますが、履歴が書き換わるので共同作業者との連携が重要です。
  3. ストレージ容量や課金プラン
    • Git LFS を使用する場合、無料プランでもある程度の容量が使えますが、上限を超えると課金が必要になる場合があります。
    • 大容量データを長期にわたり管理する場合は、GitHub の課金プランや代替のストレージサービスの利用も検討してください。

6. まとめ

  • GitHub は 100MB を超えるファイルのプッシュを原則禁止しています。
  • 大容量ファイルを扱う場合は Git LFS の導入が推奨されます。
  • どうしてもリポジトリに含めない方が良い場合は .gitignore を利用してコミットを除外します。
  • 既に大容量ファイルをコミットしてしまった場合は、過去の履歴から削除する必要があるため注意が必要です。

参考リンク

以上が、スクリーンショットに示された警告メッセージ(「100MB を超えるファイルがある」等)を踏まえた大容量ファイルの管理に関する資料の一例です。ご自身のプロジェクトの状況に合わせて、ファイルの除外や Git LFS の導入などを検討してみてください。