Git LFS で困った時に読むやつ
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
参考
感想
奥深い。。。
公式が丁寧に解説してくれているので、英語で読んでみるのも一興ですね!
Discussion