Git LFSを使って巨大ファイルをGitHubで管理する

初めに

GitHubには、一度にPUSHできる容量の制限があり、大きなファイルはPUSHできません。
この記事ではそれを解決するGit LFSの簡単な使い方についてまとめます。

課題：GitHubでは100MB以上のファイルをPUSHできない

GitHubでは、一度にPUSHできるファイルサイズに制限があります。
上限は100MBです。

100MB以上のファイルをPUSHしようとする

> git push
remote: error: See https://gh.io/lfs for more information.
remote: error: File largeFile/largefile is 200.00 MB; this exceeds GitHub's file size limit of 100.00 MB

合計で100MBを超えた場合は100MBを超えないように分割してPUSHすれば問題ありませんが、一つのファイルが100MBを超えている場合はどう頑張ってもPUSHすることができません。

解決策：Git LFSを使えば大きなファイルをGitHubにPushできる

この問題を解決するのが、Git Large File Storage（Git LFS）です。
巨大ファイルを専用の別ストレージに管理し、そのポインターをリポジトリに格納するというものになります。

Git LFSを試してみる

では、Git LFSを使って大きなファイルをアップロードしてみましょう。
環境はWindows11 Proです。

1. Git LFSのインストール

以下からGit LFSをインストールしましょう。

私の環境では、Git for Windowsに付属していたのか、最初からインストールされていました。

> git lfs --version
git-lfs/3.6.1 (GitHub; windows amd64; go 1.23.3; git ea47a34b)

2. Git LFSで管理するファイルを選ぶ

git lfs trackコマンドでGit LFSで管理するファイルを選択します。

> git lfs track .\largeFile\largefile
Tracking "largeFile/largefile"

すると、プロジェクト直下に.gitattributesというファイルが作成されます。
どうやらこのファイルに、Git LFSで管理するファイルが記録されるようです。

.gitattributes

largeFile/largefile filter=lfs diff=lfs merge=lfs -text

3. コミット

まずは.gitattributesをコミットしましょう。
その後、Git LFSで管理したファイルをコミットすれば完了です。

GitHubにアップロードされるのは、実際のファイルではなくポインタです。実態はGitHubのストレージに格納されています。
また、Git LFSで管理されているファイルにはStored with Git LFSという記載があり、一目で分かるようになっています。

Git LFSの注意点

無料枠は2GBまで

2025年3月時点で、GitHubのGit LFSの無料枠は2GBまでです。それ以上を超える場合は有料になります。

アップロードしたファイルを削除するにはリポジトリごと消す必要がある

リポジトリからポインタを削除するとアップロードしたファイルの紐づけを消すことはできますが、サーバにはファイルが残り続けます。削除するにはリポジトリを削除するかサポートに連絡するしか方法がないようです。
誤ってアップロードしないように注意しましょう。

Git LFSサーバを自前で用意したという記事もあるので、そうすればこのような問題も解決できるかもしれません。

終わりに

今回はGit LFSを用いて巨大ファイルをGitHubにアップロードする方法を解説しました。
今度は自前でLFSサーバを用いる方法も試してみたいところです。

ここまでご覧いただきありがとうございました！