Git Large File Storage

Bitbucket Data Center と Server の管理

このページの内容

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

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 Data Center and 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. Learn more about Git LFS

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 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 Proxy and secure Bitbucket for more info. 

The Data Center Migration Tool does not export Git LFS

For more information see LFS Migration


Enable Git LFS for a repository

Git LFS is disabled by default.

To enable Git LFS:

  1. Go to Repository settings > Large file storage (LFS).
  2. Select Allow LFS
  3. Select Save. 

If you cannot select Allow LFS, this is because the instance administrator has disabled LFS support on the instance.

Install and use the Git LFS command line client

Git LFS は、標準 Git ワークフローとできるだけシームレスに連携することを目指しています。

To push your first Git LFS files to an existing repository:

  1. Enable Git LFS support for the repository (see above).
  2. Download and install the git-lfs command line client.
  3. 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

    上記の変更はグローバルに適用されるので、作業を行う各リポジトリに対してこれを実行する必要はありません。

  4. Choose the file types you would like LFS to handle by executing the git lfs track command. The git lfs track command creates or updates the .gitattributes file in your repository. 
    Change to your cloned repository, then execute git add to ensure updates to the .gitattributes are later committed:

    git lfs track "*.jpg"
    git add .gitattributes
  5. 通常どおりに変更を追加、コミット、およびプッシュします。

    git add image.jpg
    git commit -m "Added an image"
    git push

    プッシュすると、Git ツリーが更新され、実際のファイル コンテンツへのポインターが含まれます。このポインターには、オブジェクトの SHA256 ハッシュとそのサイズ (バイト単位) が含まれます。例:

    oid sha256:4fa32d6f9b1461c4a53618a47324e243e36ce7ceae72ad440cc811a7e6881be1
    size 1580060

    The object itself will be uploaded to a separate location via the Git LFS Batch API. Specifically, the object will be uploaded to an embedded LFS object store within your Bitbucket instance.

Disable Git LFS

Git LFS support is enabled by default. It can, however, be disabled. This will prevent upload or download of LFS objects for all repositories, but it won't delete existing LFS objects stored within Bitbucket.

To disable Git LFS:

  1. Log in with sysadmin permissions.
  2. Go to  > Server settings.
  3. Untick Git LFS enabled.
  4. [保存] を選択します。

埋め込みのオブジェクト ストア

Bitbucket 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 ファイルとして認識されません。

スマート ミラーリング

Smart Mirroring supports mirroring of Git LFS objects as of Bitbucket 4.5. Mirroring of Git LFS objects is performed on-demand; that is, when a client requests download of a Git LFS object from the mirror node, the object will be streamed from the upstream node if it is not already available on the mirror. Subsequent downloads of the same object will be downloaded directly from the copy stored on the mirror.

Limit Disk Space Usage

By default Bitbucket won't permit Git LFS uploads if the amount of free disk space in the filesystem that hosts the storage directory has less than 100 megabytes of free disk space. When a client attempts to upload (via a Git push) an LFS file that would result in the free disk-space threshold being exceeded, an error message indicating as such is sent to the client:

$ 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

The free disk-space threshold can be tuned by adding the following property to the  config properties file (this example tunes the threshold to one gigabyte, and note that this value is in bytes):

plugin.bitbucket-git-lfs.minimum.free.space=1073741824

値をゼロに設定すると、空きディスク スペースの検査は無効になり、利用可能なディスク スペースがない場合でもファイルをアップロードできるようになります。ただし、これは推奨されません。システムがすべてのディスク スペースを使い果たしているにもかかわらず、空きスペースがない旨のエラー メッセージをログに記録できない (ディスクが満杯のため) 状況を招くおそれがあります。その結果、ディスク スペースが満杯であることで生じるさまざまな問題のデバッグが困難になります。

plugin.bitbucket-git-lfs.minimum.free.space=0

Bitbucket must be restarted for the change to take effect.

Limit Network Connections

Large Git LFS download or upload operations over very slow network links could take many minutes, or even hours. Bitbucket 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  config properties file. Bitbucket must be restarted 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)
最終更新日: 2023 年 2 月 26 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.