Git LFS入門：大きいファイルをコミットしてしまったときの対処法

はじめに

Gitでうっかり大きいファイルをコミットしてしまったことはないでしょうか。

remote: error: File assets/video.mp4 is 256.00 MB; this exceeds GitHub's file size limit of 100 MB.

GitHubにプッシュしようとしたらこんなエラーが出た、という経験をした方も多いはずです。この記事では Git LFS（Large File Storage）を使って大きいファイルをGitで管理する方法と、すでにコミットしてしまったファイルを後からLFS管理に移行する手順を解説します。

Git LFSとは

Git LFSはGitリポジトリで大きいファイルを扱うための拡張機能です。

通常のGitは変更のたびにファイル全体をオブジェクトとして保存するため、大きいファイルを何度も変更するとリポジトリのサイズが膨大になります。Git LFSはこの問題を解決するために、大きいファイルの実体を別のストレージに保存し、Gitリポジトリ内にはポインタファイル（テキストファイル）だけを置く仕組みです。

# ポインタファイルの中身（実際のファイルの代わりにこれだけが保存される）
version https://git-lfs.github.com/spec/v1
oid sha256:a3b2c1d4e5f6...
size 268435456

インストール

Mac（Homebrew）

brew install git-lfs

Windows

git-lfs.github.com からインストーラーをダウンロードします。

インストール後の初期設定

git lfs install

これでGitのグローバル設定にLFSのフックが追加されます。一度実行すれば以後は不要です。

新規リポジトリでの設定

追跡するファイルの種類を指定します。

# 動画ファイルを追跡対象に追加
git lfs track "*.mp4"
git lfs track "*.mov"

# 画像ファイル
git lfs track "*.psd"
git lfs track "*.ai"

# バイナリファイル
git lfs track "*.zip"
git lfs track "*.dmg"

このコマンドを実行すると .gitattributes ファイルが作成・更新されます。

# .gitattributes
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.mov filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text

.gitattributes はコミットしてリポジトリで管理します。

git add .gitattributes
git commit -m "Add git-lfs tracking rules"

以降は対象の拡張子のファイルを git add すると自動的にLFSで管理されます。

すでにコミットしてしまったファイルをLFSに移行する

問題が起きるのはたいていこのケースです。すでにコミット済みの大きいファイルをLFS管理に移行するには git lfs migrate コマンドを使います。

現在のブランチのみ移行する場合

git lfs migrate import --include="*.mp4"

全ブランチを対象にする場合

git lfs migrate import --include="*.mp4" --everything

移行が完了したら強制プッシュが必要です。

git push origin main --force

複数人で使っているリポジトリの場合、強制プッシュ後は全員が以下を実行する必要があります。

git pull --rebase

クローン・プル時の注意点

LFSを使っているリポジトリをクローンした場合、デフォルトでLFS管理のファイルも自動でダウンロードされます。

ただし大きいファイルが多い場合はクローンに時間がかかります。LFSファイルを後でダウンロードしたい場合は以下のようにします。

# LFSファイルをスキップしてクローン
GIT_LFS_SKIP_SMUDGE=1 git clone <repository-url>

# 後から必要なファイルだけ取得
git lfs pull

現在の追跡状況を確認する

# 追跡対象のルールを確認
git lfs track

# LFS管理されているファイルの一覧
git lfs ls-files

# LFSの使用容量を確認
git lfs status

GitHubでのLFSの制限

GitHubではLFSのストレージと転送量に制限があります。

プラン	無料枠
ストレージ	1GB
月間転送量	1GB

超過した場合はデータパックを購入するか、LFSの対象ファイルを見直す必要があります。大きいファイルを頻繁に更新するリポジトリでは使用量に注意してください。

まとめ

Git LFSは大きいファイルの実体を別ストレージに保存し、リポジトリの肥大化を防ぐ
git lfs track "*.mp4" で追跡対象を指定する
すでにコミット済みのファイルは git lfs migrate import で移行できる
移行後は強制プッシュと全員の git pull --rebase が必要
GitHubの無料枠はストレージ・転送量とも1GB