Unity│Git LFSの設定｜.gitattributesと大きいファイルの扱い

2026年9月29日2026年10月26日

Git LFSは、大きいバイナリの実体をLFSオブジェクトとして保存し、Gitのコミットには参照情報を入れる仕組みです。

ここでは、新しいファイルの登録と、既存ファイルを今後のコミットからLFSへ切り替える方法を分けます。

前提とLFSに登録するファイル

GitとGit LFSを導入済みの練習用リポジトリで、コマンドプロンプトから実行します。

例のbody.pngとchara.fbx、および対応する.metaは事前に用意したファイルです。

パスは実際の素材名へ置き換えます。

PNGやFBXなど、Gitで内容の差分を扱いにくい素材を対象にします。

*.pngはbody.png.metaには一致しません。

.metaは通常のGitで素材と一緒に管理します。

拡張子を広く追加する前に、サイズと変更頻度を確認してください。

新しいファイルをLFSでコミットする

git lfs install --local
git lfs track "*.png" "*.fbx"
git add -- .gitattributes "Assets/Textures/body.png" "Assets/Textures/body.png.meta" "Assets/Models/chara.fbx" "Assets/Models/chara.fbx.meta"
git diff --cached --stat
git commit -m "Track practice binary assets with LFS"
git lfs ls-files
git check-attr filter -- "Assets/Textures/body.png" "Assets/Textures/body.png.meta" "Assets/Scenes/Test.unity"
git show HEAD:Assets/Textures/body.png

--localは、このリポジトリにLFSの設定とフックを入れる指定です。

git lfs trackは.gitattributesを作成・更新するため、素材と一緒にコミットします。

既存の.gitattributesにほかのルールがある場合は残し、差分を確認してください。

git lfs ls-filesにはPNGとFBXが出ます。

git check-attrではPNGのfilterがlfs、.metaと通常のシーンはunspecifiedになります。

別の既存ルールがある場合は結果が変わるため、意図せず.metaやシーンまでLFSになっていないか確認します。

既存のフックが原因でgit lfs installに失敗する場合は、git lfs install --manualで統合手順を表示できます。

フックはGitの操作に合わせて実行される処理です。

元の処理を残す必要がある場合は、表示された手順を確認してLFSの処理を組み込んでください。

ポインターと手元の実体を区別する

git show HEAD:Assets/Textures/body.pngは、コミットに保存されたポインターを表示します。

version・oid sha256・sizeの行があり、sizeは元のPNGのバイト数です。

エクスプローラーなどで見る作業ツリーのbody.pngは、取得済みなら元画像のままです。

ローカルのコミットだけでは外部サーバーへアップロードされません。

共有先へpushするには、そのホストのLFS対応と必要なオブジェクトの送信を確認します。

今回の検証には外部へのpush・cloneを含めていません。

既存ファイルを今後のコミットからLFSへ切り替える

git lfs migrate import --everythingによる通常の履歴移行は、過去のコミットを広く書き換える処理です。

まずは以下のgit add --renormalizeで、指定したPNGだけを現在のインデックスへ入れ直す方法を使います。

実行前に未コミットの作業と既存のステージを確認し、今回と無関係な変更を同じコミットに含めないようにしてください。

git status --short
git lfs install --local
git lfs track "*.png"
git add -- .gitattributes
git add --renormalize -- "Assets/Textures/body.png"
git diff --cached --stat
git commit -m "Use LFS for body.png from this commit"
git lfs ls-files

新しいコミットのPNGはLFSポインターになります。

過去のコミットIDと、その中の元データは変わりません。

そのため、過去に入れた巨大ファイルによる履歴の容量はこの操作だけでは減りません。

コミット前に取り消す場合は、git restore --staged -- .gitattributesと対象PNGでステージを戻し、.gitattributesの今回追加した行だけを編集で元へ戻します。

コミット後はチームの手順で対象差分を戻し、force pushで履歴を合わせないでください。

過去の容量を整理する目的の履歴移行は、別の作業として全参照・バックアップ・共同作業者への影響を確認します。

範囲や書き換えの仕様はgit lfs migrateの公式説明を参照してください。

画像がポインターのまま・取得できないとき

ファイルを開いたときにversion https://git-lfs.github.com/spec/v1が見える場合は、画像の実体を取得できていない可能性があります。

LFSが導入済みか、認証と共有先に必要なオブジェクトがあるかを確認します。

正しい共有先に接続できる環境ではgit lfs pullで現在の参照に必要な実体を取得できます。

未取得のデータを適当な画像や.metaの再生成で置き換えず、元の素材を持つ作業者へ確認してください。

git lfs fsckはローカルの整合性確認に使えますが、サーバーに全履歴の実体があることを証明するものではありません。

git lfs pullを引数なしで実行すると、追跡中のブランチに対応するリモート、またはoriginから取得します。

複数の共有先がある場合は、意図した取得元かを確認してください。

取得できないファイルが一部だけの場合は、lfs.fetchincludeとlfs.fetchexcludeの設定も確認します。

これらは取得するパスを絞る設定で、除外されたファイルはgit lfs pullを繰り返しても取得されません。

Git 2.42.0以降の通常のリポジトリでは、インデックスの対象ファイルとLFS属性も取得条件になります。

一部だけをチェックアウトする運用では、必要な.gitattributesが取り出されているかも確認してください。

git lfs fsckは、破損ファイルを見つけると.git/lfs/badへ移動します。

変更を伴わない点検だけと考えず、重要な作業ではコピーやバックアップを用意してから実行してください。

また、lfs.fetchexcludeに一致するファイルは整合性検査からも除外されます。

根拠：Git LFS 3.7.1の公式説明（install、pull、fsck、2026年10月26日確認）。

追加した取得制限・フック統合・破損検査の説明は文書照合で、以下の過去の実測には含まれません。

シーン・プレハブとUnity側の検証範囲

Force Textで保存した.unity・.prefabは文字の差分を扱えるため、この例ではLFSへ登録しません。

バイナリ形式で保存しているプロジェクトに、その前提をそのまま当てはめないでください。

結合を行うUnityYAMLMergeの設定はUnity Smart Mergeの公式手順で確認します。

Editorと実際のシーンの結合は今回未検証です。

2026年10月2日、Git 2.54.0.windows.1・Git LFS 3.7.1で、新規PNG・FBXの登録、ポインターのハッシュとサイズ、.metaの通常管理、既存PNGの切り替え後も過去のコミットと作業ツリーのバイトが保持されることを確認しました。

Unity素材のインポート検証は含みません。