sumisonic notes

Git LFS (Large File Storage)

5 min read

概要

Git LFS (Large File Storage) は Git の拡張機能で、大きなファイル（音声、動画、画像、モデルファイルなど）をリポジトリ本体から分離して管理する仕組み。

  • リポジトリにはポインタファイル（テキスト、~130バイト）だけを保存
  • ファイルの実体は別の LFS サーバーに保存される
  • git clone や git pull 時に透過的にダウンロードされる
  • GitHub, GitLab, Bitbucket が標準サポート

LFS サーバーの仕組み

LFS サーバーは Git ホスティングサービスに組み込まれている。Google Drive のような外部ストレージとは異なり、=git push= するだけでポインタはリポジトリへ、実体は LFS サーバーへ自動的に振り分けられる。

  • GitHub → GitHub の LFS ストレージに自動アップロード
  • GitLab → GitLab の LFS ストレージに自動アップロード
  • セルフホストも可能（S3, MinIO などをバックエンドにした LFS サーバーを構築）

ユーザー側は git push / git pull するだけで、LFS サーバーとのやりとりを意識する必要はない。

セットアップ

# インストール（macOS）
brew install git-lfs
 
# Git LFS を有効化（グローバル、初回のみ）
git lfs install

基本的な使い方

トラッキング対象の設定

# 拡張子で指定
git lfs track "*.aif" "*.mp4" "*.safetensors"
 
# ディレクトリで指定
git lfs track "assets/**"
 
# .gitattributes が自動生成される → 必ずコミット
git add .gitattributes
git commit -m "Configure Git LFS tracking"

通常のワークフロー

LFS 設定後は通常通り git add / git commit / git push するだけ。Git が自動的にポインタファイルへの変換と LFS サーバーへのアップロードを行う。

git add assets/large_video.mp4
git commit -m "Add video"
git push

確認コマンド

# トラッキング対象の確認
git lfs track
 
# LFS 管理下のファイル一覧
git lfs ls-files
 
# LFS の状態確認
git lfs status

ホスティングサービスごとの制限と料金

GitHub

項目FreePro ($4/月)Team ($4/人/月)Enterprise
LFS ストレージ1 GB1 GB1 GB1 GB
LFS 帯域（月間）1 GB1 GB1 GB1 GB
Data Pack（$5/月）+50 GB / +50 GB同左同左同左
  • ファイルサイズ上限: 2 GB/ファイル
  • 全プランとも LFS の基本枠は同じ（1 GB）。増量には Data Pack の購入が必要
  • 帯域は git clone / git pull / git lfs fetch で消費される
  • GitHub の Settings → Billing で使用量を確認可能

GitLab

項目FreePremium ($29/人/月)Ultimate ($99/人/月)
LFS ストレージ5 GB（プロジェクト全体）50 GB250 GB
転送量制限10 GB/月100 GB/月500 GB/月
  • GitLab はプロジェクト全体のストレージ枠に LFS が含まれる
  • GitHub より無料枠が大きい（5 GB vs 1 GB）
  • 追加ストレージ: $60/年 で 10 GB 追加
  • セルフホスト GitLab なら制限なし

注意点

後から LFS に移行する場合

既にコミット済みの大きなファイルを後から LFS に移行するには git lfs migrate が必要。Git 履歴の書き換えが発生するため、チームで使っている場合は注意。

# 既存の .aif ファイルを LFS に移行（履歴含む）
git lfs migrate import --include="*.aif" --everything
git push --force-with-lease --all

クローン時の挙動

git clone すると LFS ファイルも自動ダウンロードされる。帯域を節約したい場合：

# LFS ファイルをダウンロードせずにクローン
GIT_LFS_SKIP_SMUDGE=1 git clone <url>
 
# 必要なファイルだけ後からダウンロード
git lfs pull --include="*.mp4"

.gitattributes は必ずコミットする

git lfs track で生成される .gitattributes をコミットし忘れると、他の環境で LFS が効かない。

コスト意識

GitHub の無料枠（1 GB ストレージ / 1 GB 帯域）は小さいため、大量のメディアファイルを扱う場合は Data Pack の購入か、セルフホスト LFS サーバーの検討が必要。GitLab の無料枠（5 GB）のほうが余裕がある。

代替手段との比較

手法特徴向いているケース
Git LFSGit に統合、透過的チーム開発、CI/CD連携
.gitignore + 外部ストレージシンプル、コスト無料個人プロジェクト、素材の再現性不要
DVCデータパイプライン対応ML プロジェクト、データセット管理

グラフビュー