Git Large File Storage
Git Large File Storage (LFS) is a Git extension that improves how large files are handled. It replaces them with tiny text pointers that are stored on a remote server instead of in their repository, speeding up operations like cloning and fetching.
Bitbucket Server ships with Git LFS enabled at an instance level, but disabled for each repository. It also includes an embedded LFS object store, removing the need for an external one.
On this page
重要な注意事項
HTTP(S) must be enabled
Git LFS supports SSH remotes, but downloading and uploading objects is done via HTTP(S). If SCM connections to Bitbucket over HTTP(S) are not enabled, Git LFS will not work.
The Bitbucket Server base URL should also be configured to a HTTP(S) URL.
We recommend configuring SSL
If your instance is available over the internet, usernames, passwords, and other data may be at risk. See Proxying and securing Bitbucket Server for more info.
The Data Center Migration Tool does not export Git LFS
For more information see LFS Migration.
リポジトリで Git LFS を有効化する
Bitbucket Server 内では、Git LFS は既定で無効化されています。
Bitbucket で Git LFS を有効化する方法
- [リポジトリ設定] > [ラージ ファイル ストレージ (LFS)] に移動します。
- [LFS を許可する] オプションを選択します、。
- 設定を保存します。
[LFS を許可する] チェックボックスが選択できない (グレーアウトされている) 場合、インスタンスの管理者がインスタンスで LFS のサポートを無効化しています。
Git LFS コマンド ライン クライアントのインストールと使用
Git LFS は、標準 Git ワークフローとできるだけシームレスに連携することを目指しています。
最初の Git LFS ファイルを既存のリポジトリにプッシュする方法
- Git LFS を使用したいリポジトリで Bitbucket Server の Git LFS サポートを有効化します (上記を参照)
- git-lfs コマンド ライン クライアントをダウンロードしてインストールします。
Git LFS フィルターをインストールします。
git lfs install
This adds the following lines to the
.gitconfig
file located in your home directory:[filter "lfs"] clean = git-lfs clean %f smudge = git-lfs smudge %f required = true
上記の変更はグローバルに適用されるので、作業を行う各リポジトリに対してこれを実行する必要はありません。
Choose the file types you would like LFS to handle by executing the
git lfs track
command. Thegit lfs track
command creates or updates the.gitattributes
file in your repository.
Change to your cloned repository, then executegit add
to ensure updates to the.gitattributes
are later committed:git lfs track "*.jpg" git add .gitattributes
通常どおりに変更を追加、コミット、およびプッシュします。
git add image.jpg git commit -m "Added an image" git push
プッシュすると、Git ツリーが更新され、実際のファイル コンテンツへのポインターが含まれます。このポインターには、オブジェクトの SHA256 ハッシュとそのサイズ (バイト単位) が含まれます。例:
oid sha256:4fa32d6f9b1461c4a53618a47324e243e36ce7ceae72ad440cc811a7e6881be1 size 1580060
オブジェクト自体は Git LFS Batch API を介して別の場所にアップロードされます。具体的には、オブジェクトは Bitbucket Server インスタンス内の組み込みの LFS オブジェクト ストアにアップロードされます。
Bitbucket で Git LFS を無効化する
Bitbucket Server はインスタンスの Git LFS のサポートが既定で有効化された状態で出荷されますが、これは無効化することができます。これにより、すべてのリポジトリで、LFS オブジェクトのアップロードとダウンロードを防ぐことができます。ただし、Bitbucket Server 内に保存されている既存の LFS オブジェクトは削除されません。
Bitbucket Server インスタンス全体で Git LFS を無効にする方法
- システム管理権限で Bitbucket Server にログインします。
- [管理] > [サーバー設定] の順に選択します。
- [Git LFS は有効化です] オプションを選択解除します。
- 設定を保存します。
埋め込みのオブジェクト ストア
Bitbucket Server includes an embedded LFS object store. Uploaded Git LFS objects are stored in the directory $BITBUCKET_HOME/shared/data/git-lfs/storage
. This storage location cannot be changed, as for clustered deployments it is critical that LFS object storage reside on the shared
filesystem so it is globally visible to all cluster nodes.
リポジトリのフォーク
LFS が有効化されたリポジトリは、フォークと、完全なフォーク ベースのワークフローをサポートします。これには、フォーク間のプル リクエストとフォーク同期が含まれます。フォークは、フォークと元のリポジトリとの間でオブジェクトを共有することで実装されるため、軽量です。つまり、フォークの作成時にはオブジェクトが複製されないので、フォークを作成する方が早くなります。
マージ競合の解決は、特に 2 つの LFS オブジェクト間にマージの競合が存在する場合、非 LFS のケースとはわずかに異なります。Git リポジトリには単純に LFS ポインターが含まれるため、競合の解決は競合しているポインター ファイルで実行する必要があります。
このような競合は次のように表示されます。
ユーザーは引き続き、通常どおり、コマンド ラインの Git クライアントを使用してマージの競合を手動で解決する必要があります。これはポインターのみであるため、マージ戦略は、1 つまたは 2 つのペア (oid / サイズ) を保持する、自身または他者に基づいたものになります。競合を解決しているときにポインター ファイルが破損した場合、それは LFS ファイルとして認識されません。
スマート ミラーリング
Bitbucket Server 4.5 の時点で、Bitbucket Server のスマート ミラーリング機能は Git LFS オブジェクトのミラーをサポートしています。Git LFS オブジェクトのミラーリングはオンデマンドで実行されます。つまり、クライアントがミラー ノードから Git LFS オブジェクトをダウンロードすることをリクエストし、そのオブジェクトがミラーでまだ利用できない場合、オブジェクトが上流のノードからストリーミングされます。同じオブジェクトの以降のダウンロードは、ミラーに保存されているコピーから直接行われます。
ディスク スペースの使用量を制限する
デフォルトでは、ストレージ ディレクトリをホストするファイルシステムのディスク空き容量が 100 メガバイト未満であった場合、Bitbucket Server は以降の Git LFS のアップロードを許可しません。クライアントが (Git プッシュ経由で) LFS ファイルをアップロードしようとしたが、それによってディスクの空き容量のしきい値が超過する場合、次のようなエラー メッセージがクライアントに送信されます。
$ git push
Git LFS: (0 of 1 files, 1 skipped) 0 B / 348.59 MB, 348.59 MB skipped
[a39717817507d0ae3434a36347159e4970aec061c8c506f197c0eeadd2e8efe2] Insufficient free space in store
error: failed to push some refs to 'https://bitbucket.example.com/bitbucket/scm/myproject/myrepo.git'
A warning will also be logged in the atlassian-bitbucket.log
file. For example:
2016-01-01 18:00:00 WARN [http-nio-7990-exec-2] user @G6I7R6x969x556x0 0:0:0:0:0:0:0:1 "POST /scm/myproject/myrepo.git/info/lfs/objects/batch HTTP/1.1" c.a.b.i.s.g.l.s.e.EmbeddedStoreAccessor Upload rejected due to insufficient free space in store - Required: 1073741824 Free: 10485760
ディスクの空き容量のしきい値は、Bitbucket Server の設定プロパティファイルに次のプロパティを追加することで調整できます (この例では、しきい値を 1 ギガバイトに調整しています。この値はバイト単位です)。
plugin.bitbucket-git-lfs.minimum.free.space=1073741824
値をゼロに設定すると、空きディスク スペースの検査は無効になり、利用可能なディスク スペースがない場合でもファイルをアップロードできるようになります。ただし、これは推奨されません。システムがすべてのディスク スペースを使い果たしているにもかかわらず、空きスペースがない旨のエラー メッセージをログに記録できない (ディスクが満杯のため) 状況を招くおそれがあります。その結果、ディスク スペースが満杯であることで生じるさまざまな問題のデバッグが困難になります。
plugin.bitbucket-git-lfs.minimum.free.space=0
変更を有効にするには、Bitbucket Server の再起動が必要です。
ネットワーク接続を制限する
Large Git LFS download or upload operations over very slow network links could take many minutes, or even hours. Bitbucket Server supports a finite number of HTTP connections (by default 200). If Git LFS were permitted to exhaust this connection pool then the user interface, Git hosting, and REST API access could be impacted. For this reason a default limit of 80 concurrent Git LFS connections are permitted. This limit can be increased or decreased if necessary by overriding the throttle.resource.git-lfs=
setting in the Bitbucket Server config properties file. A Bitbucket Server restart is required for the change to take effect.
クライアントがオブジェクトをアップロードまたはダウンロードするリクエストを行ったが、そのリクエストによって同時接続の最大数が超過する場合、HTTP ステータス 503 が返され、次のエラーがクライアントに送信されます。
The requested resource is busy and cannot service your request. Please try again later
The atlassian-bitbucket.log
file will also contain an associated warning:
2016-01-01 18:00:00 WARN [http-nio-7990-exec-3] username @1HJ1OF1x1115x417x1 0:0:0:0:0:0:0:1 "GET /rest/git-lfs/storage/myproject/myrepo/3a9219fde5bc436a2fc37cdd38bdb8478a210c7a49405dd9603ccdc95ed39613 HTTP/1.1" c.a.s.i.t.SemaphoreThrottleService A [git-lfs] ticket could not be acquired (0/80)