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

2026年9月29日2026年10月2日

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 show HEAD:Assets/Textures/body.pngは、コミットに保存されたポインターを表示します。version・oid sha256・sizeの行があり、sizeは元のPNGのバイト数です。エクスプローラーなどで見る作業ツリーのbody.pngは、取得済みなら元画像のままです。

ローカルのコミットだけでは外部サーバーへアップロードされません。共有先へpushするには、そのホストのLFS対応と必要なオブジェクトの送信を確認します。今回の検証には外部へのpush・cloneを含めていません。

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

旧版の–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はローカルの整合性確認に使えますが、サーバーに全履歴の実体があることを証明するものではありません。

シーン・プレハブと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素材のインポート検証は含みません。

関連：Unityの.gitignore設定。仕様：git add –renormalize、Git LFS FAQ。