Git LFS とは

Git Large File Storage の略称。
大容量ファイルを Git リポジトリで管理する際に用いる 拡張機能。
GitHub では 100 MB 以上のファイルをバージョン管理する場合、LFS の使用が必要。

インストール & 初期化

$ brew update
$ brew install git-lfs
$ git lfs install
$ git lfs version

上記で Git LFS のインストールと初期化が完了します。
初期化は Git アカウントごとに 1 回行えば OK です。 Git リポジトリごとに何度も実行する必要はありません。

新規ファイルを LFS 管理する方法

たとえば mp4 ファイルを LFS 管理したい場合は以下のよう設定します。

$ git lfs track "*.mp4"
$ git add sample.mp4
$ git commit -m 'sample.mp4をGit LFSで管理する'
$ git push origin main

track を実行することで管理対象が .gitattributes に追記されます。
track は LFS 管理対象を指定するだけで、実際に管理するためには track 実行後にsample.mp4 を git add → git commit → git push する必要があります。

注意点

git lfs track は track 実行以降に追加されたファイルのみを LFS 管理します。既存ファイルを後から LFS 管理したい場合は git lfs migrate を使います。
LFS で管理されたファイルは Git リポジトリへは Push されません。LFS サーバと呼ばれる大容量ファイルを管理する専用のサーバに Push されます（詳細は後述）。Git リポジトリへは LFS ポインタファイル（詳細は後述）と呼ばれる実際にファイルが格納された場所を指し示す数行のテキストファイルのみが Push されます。

既存ファイルを LFS 管理する方法

既存のコミット履歴に含まれる大きなファイルを後から LFS に移行したいときは、git lfs migrate を使います。

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

これにより、過去のコミット履歴に登場するすべての *.mp4 を LFS 管理へ変換し、既存のリポジトリに含まれる大容量ファイルをクリーンアップできます。

LFS サーバとは？

LFS サーバとは Git LFS で管理された大容量ファイルを管理する専用のファイルサーバです。
LFS 管理されたファイルは Git リポジトリへは Push されません。LFS サーバに Push されます。

LFS サーバはどこにある？

lfs env で確認できます。
LFS サーバの所在は Git リポジトリをクローンしたり Git リモートを追加したりした際にデフォルト値が決まります。

$ git lfs env

Endpoint=https://example.com/path/myrepo.git/info/lfs (auth=none)
LocalWorkingDir=C:\src\myrepo
LocalGitDir=C:\src\myrepo\.git
LocalGitStorageDir=C:\src\myrepo\.git
LocalMediaDir=C:\src\myrepo\.git\lfs\objects
TempDir=C:\src\myrepo\.git\lfs\tmp
ConcurrentTransfers=3
BatchTransfer=true
git config filter.lfs.smudge = "git-lfs smudge %f"
git config filter.lfs.clean = "git-lfs clean %f"
...etc

Endpoint を変えるには以下コマンドを実行します。

$ git config lfs.url "https://my_other_server.example.com/foo/bar/info/lfs"

ポインタファイルとは？

ポインタファイルは、LFS で管理された大容量ファイルの代わりに、Git リポジトリ内にコミットされる数行のテキストファイルです。
中身は以下のような形式（例）になっています。

version https://git-lfs.github.com/spec/v1
oid sha256:6de843d1921fcd9a6a8afdf15b2478208acdadf2051c7c6f73951d60d8940c83
size 12345678

version : ポインタファイルのバージョン情報 (Git LFS v1 など)を示します。
oid: その大容量ファイルのハッシュ (SHA-256)が記載されています。これをそのままオブジェクトの一意識別子として使用しています。
size : 実体のファイルサイズ（バイト単位）

LFS 管理済みファイルを確認する方法

実際に追跡されている全てのファイルを一覧で確認するには ls-files を実行します。

$ git lfs ls-files

一覧表示されるファイルは既にコミットされたファイルのみ一覧表示されます。つまり、ステージ（git add）されているだけのファイルは表示されません。これは実装都合上、コミットされなければLFS オブジェクトとして Git に記録されないからです。

`track` と `ls-files`の違いは？

track

track は追跡対象となるファイル名やパスパターンを一覧で出力するだけです。
「実際のファイル一覧」ではなく、あくまで「どの拡張子・パスを LFS で追跡するか」の設定を確認できます。
引数無しで git lfs track だけ実行すると、以下のように確認できます。

$ git lfs track

Listing tracked patterns
    *.mp4 (.gitattributes)
Listing excluded patterns

LFS で実際に追跡されているファイル一覧を出力するコマンドではありません。

ls-files

実際に LFS 管理されているファイル一覧を出力します。

$ git lfs ls-files

a4273525ef * sample.mp4
5dbea73ca7 * hoge.mp4
49fb8ee4cd * piyo.mp4
...etc

LFS 管理ファイルを Push する方法

通常の Git の操作と同様に git add, git commit, git push すれば自動的に LFS サーバへアップロードされます。

$ git add sample.mp4
$ git commit -m 'sample.mp4をGit LFSで管理する'
$ git push origin main

※ このとき sample.mp4 はローカルで LFS フィルタを通り、実体は LFS サーバに送られ、リポジトリにはポインタファイルがコミットされます。

LFS 管理ファイルを Pull する方法

通常の git clone, git pull では LFS のポインタファイルしかダウンロードされません。大容量ファイルの実体はダウンロードされません。
実体をダウンロードするには、以下コマンドを実行します。

$ git lfs pull
$ git lfs fetch --all ## 全ての LFS オブジェクトを一括でフェッチ
$ git lfs checkout    ## ローカルのポインタファイルを実ファイルに置き換える

Git LFS をインストールしていなければポインタファイルしか Pull できません。
自分が Push した大容量ファイルを他のメンバーにも Pull させるためには、全てのメンバーの PC に Git LFS をインストール・初期化する必要があります。

100MB 以上のファイルを確認する方法

$ cd ~/path/to/localProject
$ find . -size +100M -ls

最大何 GB までアップロードできる？

プランによって変わります。

プラン	1ファイルの最大サイズ
GitHub Free	2 GB
GitHub Pro	2 GB
GitHub Team	4 GB
GitHub Enterprise Cloud	5 GB

LFSの辞め方

Git LFS を導入したものの、何らかの理由で「もう LFS 管理をやめたい」「別のファイル管理方法に切り替えたい」と思う場合があります。
ここでは、「ファイルを削除 or 追跡を止める」といったケースを順に解説します。

LFS 追跡を止める（新規ファイルだけ非LFSにしたい場合）

「新しく追加するファイルだけはもう LFS で管理したくない」という場合、.gitattributes から該当パターンを削除、もしくは git lfs untrack すれば OKです。

$ git lfs untrack "*.mp4"

これにより、今後 *.mp4 を追加しても LFS で扱われなくなります。
しかし、すでに LFS 化されているファイルがあれば、過去コミットには LFS ポインタファイルが残ったままです。

特定の LFS 管理ファイルを削除する

対象のポインタファイルを削除します。

rm sample.mp4
git add
git commit
git push

これにより、リポジトリからファイルを削除することができます。
しかし、これでは LFS サーバにあるファイルは削除されません。
原則、LFSで管理されたファイルは削除できません。
詳細は以下記事をご覧ください。

LFS 自体を止める方法

$ git lfs uninstall
$ brew uninstall git-lfs

参考

https://git-lfs.com/

https://github.com/git-lfs/git-lfs/wiki

感想

奥深い。。。
公式が丁寧に解説してくれているので、英語で読んでみるのも一興ですね！

Discussion