正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

Git LFSのトラブルシューティング

Git LFSを使用する場合、以下の問題が発生することがあります。

  • Git LFSのオリジナルv1 APIはサポートされていません。
  • Git LFSのリクエストはHTTPS認証情報を使用します。これは、Gitの認証情報ストアを使用する必要があることを意味します。
  • グループWikiは、Git LFSをサポートしていません。

エラー：リポジトリまたはオブジェクトが見つかりません

このエラーは、いくつかの理由で発生する可能性があります。以下に例を示します:

  • 特定のLFSオブジェクトにアクセスする権限がありません。プロジェクトにプッシュする、またはプロジェクトからフェッチする権限があることを確認してください。
  • プロジェクトは、LFSオブジェクトにアクセスすることを許可されていません。プッシュ（またはフェッチ）するLFSオブジェクトは、プロジェクトで使用できなくなりました。ほとんどの場合、オブジェクトはサーバーから削除されています。
  • ローカルコピーのGitリポジトリが、非推奨バージョンのGit LFS APIを使用しています。ローカルコピーのGit LFSを更新して、もう一度試してください。

<url>の無効なステータス: 501

Git LFSは、ログファイルに失敗を記録します。このログファイルを表示するには:

  1. ターミナルウィンドウで、プロジェクトのディレクトリに移動します。

  2. 次のコマンドを実行して、最近のログファイルを表示します:

    git lfs logs last

これらの問題は、501エラーを引き起こす可能性があります:

  • Git LFSがプロジェクトの設定で有効になっていません。プロジェクトの設定を確認し、Git LFSを有効にします。

  • Git LFSのサポートがGitLabサーバーで有効になっていません。GitLab管理者に、Git LFSがサーバーで有効になっていない理由を確認してください。Git LFSサポートを有効にする方法については、LFS管理ドキュメントを参照してください。

  • Git LFSクライアントのバージョンは、GitLabサーバーでサポートされていません。以下をお勧めします:

    1. git lfs versionを使用して、Git LFSのバージョンを確認します。
    2. git lfs -lを使用して、非推奨APIの痕跡がないかプロジェクトのGit設定を確認します。設定でbatch = falseを設定している場合は、その行を削除し、Git LFSクライアントを更新します。GitLabは、バージョン1.0.1以降のみをサポートしています。

オブジェクトをプッシュするときは、常に認証情報が必要です

Git LFSは、すべてのオブジェクトのすべてのプッシュでHTTP基本認証を使用してユーザーを認証するため、ユーザーのHTTPS認証情報が必要です。デフォルトでは、Gitは使用する各リポジトリの認証情報を記憶することをサポートしています。詳しくは、Gitの公式ドキュメントをご覧ください。

たとえば、オブジェクトをプッシュすることが予想される期間、パスワードを記憶するようにGitに指示できます。この例では、1時間（3600秒）認証情報を記憶し、1時間後にもう一度認証する必要があります:

git config --global credential.helper 'cache --timeout=3600'

認証情報を保存して暗号化するには、以下を参照してください:

ユーザーの認証情報の保存の詳細については、Git認証情報ストレージドキュメントを参照してください。

プッシュでLFSオブジェクトが見つかりません

GitLabは、プッシュ時にファイルをチェックして、LFSポインターを検出します。LFSポインターが検出されると、GitLabはこれらのファイルがLFSに既に存在するかどうかを確認しようとします。Git LFSに別のサーバーを使用している場合に、この問題が発生した場合:

  1. Git LFSがローカルにインストールされていることを確認します。
  2. git lfs push --allを使用した手動プッシュを検討してください。

Git LFSファイルをGitLabの外部に保存する場合は、プロジェクトでGit LFSを無効にすることができます。

LFSオブジェクトを外部でホストする

カスタムLFS URLを設定して、LFSオブジェクトを外部でホストできます:

git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs

これは、NexusリポジトリなどのアプライアンスにLFSデータを保存する場合に実行できます。外部LFSストアを使用する場合、GitLabはLFSオブジェクトを検証できません。GitLab LFSサポートが有効になっている場合、プッシュは失敗します。

プッシュの失敗を停止するには、プロジェクトの設定でGit LFSサポートを無効にすることができます。ただし、この方法は、次のようなGitLab LFS機能も無効にするため、望ましくない可能性があります:

  • LFSオブジェクトの検証。
  • LFSのGitLab UIインテグレーション。

LFSオブジェクトをプッシュする際のI/Oタイムアウト

ネットワークの状態が不安定な場合、Git LFSクライアントはファイルのアップロードを試行する際にタイムアウトする可能性があります。次のようなエラーが表示されることがあります:

LFS: Put "http://example.com/root/project.git/gitlab-lfs/objects/<OBJECT-ID>/15":
read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout
error: failed to push some refs to 'ssh://example.com:2222/root/project.git'

この問題を修正するには、クライアントアクティビティーのタイムアウトをより高い値に設定します。たとえば、タイムアウトを60秒に設定するには:

git config lfs.activitytimeout 60

ポインターであるはずのn個のファイルが見つかりました

このエラーは、リポジトリがGit LFSでファイルを追跡する必要があるが、そうでないことを示しています。GitLab 16.10で修正されたイシュー326342は、この問題の1つの原因でした。

問題を修正するには、影響を受けるファイルを移行し、リポジトリにプッシュします:

  1. ファイルをLFSに移行します:

    git lfs migrate import --yes --no-rewrite "<your-file>"

  2. リポジトリにプッシュして戻します:

    git push

  3. オプション。.gitフォルダーをクリーンアップします:

    git reflog expire --expire-unreachable=now --all
git gc --prune=now

LFSオブジェクトは自動的にチェックアウトされません

Git LFSオブジェクトが自動的にチェックアウトされない問題が発生する可能性があります。この場合、ファイルは存在しますが、実際のコンテンツではなくポインター参照が含まれています。これらのファイルを開くと、予期されるファイルコンテンツが表示される代わりに、次のようなLFSポインターが表示される場合があります:

version https://git-lfs.github.com/spec/v1
oid sha256:d276d250bc645e27a1b0ab82f7baeb01f7148df7e4816c4b333de12d580caa29
size 2323563

この問題は、ファイル名が.gitattributesファイル内のルールと一致しない場合に発生します。LFSファイルは、.gitattributes内のルールと一致する場合にのみ自動的にチェックアウトされます。

git-lfs v3.6.0では、この動作が変更され、LFSファイルのマッチング方法が最適化されました。

GitLab Runner v17.7.0は、git-lfs v3.6.0を使用するように、デフォルトのヘルパーイメージをアップグレードしました。

ケース感度が異なるさまざまなオペレーティングシステム間で一貫した動作を実現するには、さまざまな大文字と小文字のパターンに一致するように.gitattributesファイルを調整します。

たとえば、image.jpgおよびwombat.JPGという名前のLFSファイルがある場合は、.gitattributesファイルで大文字と小文字を区別しない正規表現を使用します:

*.[jJ][pP][gG] filter=lfs diff=lfs merge=lfs -text
*.[jJ][pP][eE][gG] filter=lfs diff=lfs merge=lfs -text

ほとんどのLinuxディストリビューションなど、大文字と小文字を区別するファイルシステムでのみ作業する場合は、より単純なパターンを使用できます。例:

*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text

警告: 考えられるLFS設定の問題

GitLab UIに次の警告が表示されることがあります:

Possible LFS configuration issue. This project contains LFS objects but there is no .gitattributes file.
You can ignore this message if you recently added a .gitattributes file.

この警告は、Git LFSが有効になっていてLFSオブジェクトが含まれているにもかかわらず、プロジェクトのルートディレクトリに.gitattributesファイルが検出されない場合に発生します。Gitは.gitattributesファイルをサブディレクトリに配置することをサポートしていますが、GitLabはルートディレクトリにあるこのファイルのみをチェックします。

回避策は、ルートディレクトリに空の.gitattributesファイルを作成することです:

  1. リポジトリをクローンします::

    git clone <repository>
cd repository

  2. 空の.gitattributesファイルを作成します:

    touch .gitattributes
git add .gitattributes
git commit -m "Add empty .gitattributes file to root directory"
git push
  1. 検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. プラスアイコン（+）を選択し、新しいファイルを選択します。
  3. ファイル名フィールドに、.gitattributesと入力します。
  4. 変更をコミットするを選択します。
  5. コミットメッセージフィールドに、コミットメッセージを入力します。
  6. 変更をコミットするを選択します。