Git の依存関係

Package Manager は、Git リポジトリからパッケージを取得すると、プロジェクトへローカルにパッケージを追加します。これにより、公開されていない変更をテストすることができますが、Git リポジトリへのコントリビュートには使用できません。既存のローカル Git リポジトリをプロジェクトの依存関係として設定するには、代わりに ローカル Git リポジトリへのパス を使用します。

ノート: package.json ファイルで Git の依存関係を指定することはできません。Package Manager はパッケージ間の Git の依存関係をサポートしていないためです。Git の依存関係はプロジェクトでのみサポートされているため、Git の依存関係はプロジェクトの manifest.json ファイルでのみ宣言できます。

ヒント:Git の依存関係をリポジトリの特定のバージョン (リビジョン) に更新したい場合は、ロックされた Git の依存関係 を参照してください。

このセクションでは、以下のトピックについて説明します。

• 要件
• Git URL
  • HTTP/HTTPS プロトコルの使用
  • [#SSH プロトコルの使用](#Git-SSH)
  • FILE プロトコルの使用
  • FILE プロトコルの使用
• 拡張構文
  • Git リビジョンの指定
  • リポジトリのサブフォルダーにあるパッケージの指定
  • リビジョンとパスの同時指定
• ロックされた Git の依存関係
• Git LFS のサポート

要件

プロジェクトで Git の依存関係を使用するには、Git クライアント (最低バージョン 2.14.0) がコンピューターにインストールされており、Git の実行ファイルのパスが PATH システム環境変数に追加されていることを確認してください。

注意:Unity では、Git 2.14.0 以上で動作するように Package Manager をテストしています。2.14.0 より下のバージョンの Git を使用している場合、結果は保証されません。

リポジトリが Git LFS でファイルを追跡する場合は、Git LFS クライアントもマシンにインストールされていることを確認してください。インストールされていないと、Package Manager は LFS サーバーに保存されたファイルを取得できず、エラーメッセージや警告メッセージなしに LFS ポインターファイルをチェックアウトします。

Package Manager ウィンドウを使用して、Git リポジトリから直接パッケージをインストールすることもできます。詳細は、Git URL からのインストール を参照してください。

Git URL

Package Manager では、ローカルファイルパスを除くすべての Git プロトコル がサポートされます。依存関係として Git URL を指定するには、バージョン番号やローカルファイルパスの代わりに Git URL を使用して、追加するパッケージの名前をプロジェクトマニフェストに加えます。例えば、以下はさまざまなプロトコルを使用してリモート Git を指定する方法を示しています。

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "ssh://git@github.example.com/myuser/myrepository2.git",
    "com.mycompany.mypackage3": "file://localhost/github.example.com/myuser/myrepository3.git",
    "com.mycompany.mypackage4": "git://github.example.com/myuser/myrepository4.git",
    etc.
  }
}

Package Manager は、URL としてフォーマットされた依存関係が Git URL であることを、リポジトリパスの最後にある .git というファイル拡張子で認識します。Git リポジトリのホスティングサービスの中には、この拡張子を持つ URL をサポートしていないものもあれば、サポートしているものもあります。このため、GIT プロトコル を使用する場合や、HTTP/HTTPS、SSH、FILE URL に特別な git+ プレフィックスを加える場合には、Git の依存関係の構文では拡張子を省略することができます。

注意git+ プレフィックスは、manifest.json ファイル内の特別なマーカーで、依存関係が Git ベースであることを示します。Package Manager は、リポジトリを複製する際に、このプレフィックスを Git に渡しません。

Git がサポートする URL の形式の詳細については、Git の clone コマンドのドキュメントを参照してください。Git が使用する各種プロトコルの違いの概要は、プロトコル使用に関する Git ドキュメント を参照してください。

Git の依存関係に拡張構文を使用することもできます。

• 目的のパッケージがリポジトリのルートにない場合、リポジトリ内のパッケージのサブフォルダーへのパスを指定することができます。これは、目的のパッケージがリポジトリのルートにない場合にのみ必要です。例えば、?path=/folder1/folder2 という文字列の場合は以下の通りです。

  "https://github.example.com/myuser/myrepository.git?path=/folder1/folder2"。

  詳細は、サブフォルダーにあるパッケージの指定 を参照してください。

• ロックする Git リビジョン (タグ、ブランチ名、特定のコミットハッシュなど) を指定できます。これにより、Package Manager は常にその正確なリビジョンをロードできます。リビジョンを指定しない場合、Package Manager はデフォルトのブランチと最新のコミットでリポジトリを複製し、そのリビジョンをロックします。例えば、#v2.0.0 という文字列の場合は以下の通りです。

  "https://github.example.com/myuser/myrepository.git#v2.0.0"

  詳細は、Git リビジョンの指定 を参照してください。

HTTP/HTTPS プロトコルの使用

完全な URL で HTTPS プロトコルを使用することができます。

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git"
  }
}

Git サーバーが .git 拡張子をサポートしない場合は、特別な git+ プレフィックスを加えることができます (拡張子をつけてもつけなくても可能です)。

{
  "dependencies": {
    "com.mycompany.mypackage1": "git+https://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2"
  }
}

ノート: 他の方法として、git+ プレフィックスの代わりに GIT プロトコルを使用することもできます。詳細は、GIT プロトコルの使用 を参照してください。

リポジトリが一般に公開されている場合、GitのURLをユーザーと共有するにはHTTPSが推奨されます。なぜなら、Gitリポジトリのホスティングサービスのウェブページから URL を直接コピーアンドペーストできるからです。

リポジトリが一般に公開されておらず、HTTPS を使用している場合、認証情報を提供するためのサーバーとのやり取りができないため、リポジトリサーバーの認証に失敗します。この場合、エディターは認証に失敗したことを通知します。

このような認証の問題を回避するには、以下のいずれかを行います。

• Git 認証情報ヘルパー を使って、事前に認証します。詳細は、HTTPS Git URL でのプライベートリポジトリの使用 を参照してください。
• 代わりに SSH プロトコル を使用します。Git リポジトリのホスティングサービスで SSH キーペアを設定すると、Package Manager はシームレスにリクエストを認証できます。

#SSH プロトコルの使用

完全な URL で SSH プロトコルを使用できます。

{
  "dependencies": {
    "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git"
  }
}

Git サーバーが .git 拡張子をサポートしない場合は、特別な git+ プレフィックスを加えることができます (拡張子をつけてもつけなくても可能です)。

{
  "dependencies": {
    "com.mycompany.mypackage1": "git+ssh://git@github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git+ssh://git@github.example.com/myuser/myrepository2"
  }
}

ノート: 他の方法として、git+ プレフィックスの代わりに GIT プロトコルを使用することもできます。詳細は、GIT プロトコルの使用 を参照してください。

また、Package Manager は常に Git の依存関係として認識する SCP のようなコマンドを使うこともできます。

{
  "dependencies": {
    "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git"
  }
}

Windows での PuTTY の使用

SSH を使用して認証する場合、Git はデフォルトの場所にあるキーを使用します。ただし、PuTTY を Windows の SSH クライアントとして使用する場合は、GIT_SSH 環境変数を設定して plink.exe を指すようにする必要があります。

SSHでの認証

SSH プロトコルを使用する場合は、Unity の外部で SSH キーを設定する必要があります。特定のホストに対する認証設定の詳細については、Bitbucket、GitLab、GitHub のヘルプページを参照してください。

ノート: SSH キーをパスフレーズで暗号化すると、Package Manager はパッケージを取得できません。なぜなら、ターミナルやコマンドラインでパスフレーズを入力する方法が用意されていないからです。この場合、エディターは認証に失敗したことを通知します。認証エージェントの使用の詳細については、SSH Git URL でのパスフレーズ保護 SSH キーの使用 を参照してください。認証に ssh-agent を使用する方法の詳細については、SSH のソリューション を参照してください。

FILE プロトコルの使用

Package Manager は、適切にフォーマットされていない限り file: プレフィックスを持つ Git URL を Git の依存関係として認識しません。つまり、git+file: プロトコル、または、file: プロトコルの .git サフィックス、いずれかを使う必要があります。

{
  "dependencies": {
    "com.mycompany.mypackage1": "git+file://github.example.com/myuser/myrepository1",
    "com.mycompany.mypackage2": "git+file:///github.example.com/myuser/myrepository2",
    "com.mycompany.mypackage3": "file:///github.example.com/myuser/myrepository3.git"
  }
}

ノート: 他の方法として、git+ プレフィックスの代わりに GIT プロトコルを使用することもできます。詳細は、GIT プロトコルの使用 を参照してください。

Package Manager は代わりに、他の構文を ローカルパス として解釈します。

FILE プロトコルの使用

Package Manager は、.git パスサフィックスの有無にかかわらず git: プロトコルを認識します。

{
  "dependencies": {
    "com.mycompany.mypackage1": "git://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git://github.example.com/myuser/myrepository2"
  }
}

GIT プロトコルは git+ プレフィックスを必要とせず、サポートもしません。

拡張構文

拡張構文を使用して、特定の Git リビジョン、サブフォルダ内のパッケージ、またはその 両方 を識別できます。

拡張構文は、Unity がサポートするすべての Git プロトコルで使用できます。

Git リビジョンの指定

Package Manager に複製させたい特定のリビジョンを宣言するには、URL の最後に記号 (#) と “revision” (リビジョン) を加えます。

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git#revision",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2#revision"
  }
}

“revision” には、任意のタグ、ブランチ、コミットハッシュを指定できます。完全なコミットハッシュを指定する必要があります。Unity は短縮 SHA–1 ハッシュをサポートしていません。この表は、リビジョンを指定する例です。

構文	URL 例
最新のデフォルトブランチ	"https://github.example.com/myuser/myrepository.git"
特定のブランチ	"https://github.example.com/myuser/myrepository.git#my-branch"
具体的なバージョン	"https://github.example.com/myuser/myrepository.git#v2.0.0"
コミットハッシュ	"https://github.example.com/myuser/myrepository.git#9e72f9d5a6a3dadc38d813d8399e1b0e86781a49"

リポジトリのサブフォルダーにあるパッケージの指定

Git の URL 構文を使ってリポジトリを指定した場合、Package Manager は、パッケージがリポジトリのルートになければならないと仮定します。しかし、パッケージの中には、リポジトリのルートレベルにないものもありますし、リポジトリの中には複数のパッケージが含まれているものもあります。

Git の URL で path クエリパラメーターを使用して、Package Manager にパッケージを見つける場所を通知することができます。指定するパスは、リポジトリのルートからの相対パスである必要があり、指定するサブフォルダーには、パッケージマニフェスト (package.json ファイル) が含まれている必要があります。

Git の依存関係にあるリポジトリのサブフォルダーを指定するには、path クエリパラメーターを使用します。

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/subfolder"
  }
}

この場合、Package Manager は、指定されたリポジトリのサブフォルダーにあるパッケージを登録し、リポジトリの残りの部分は無視します。

リポジトリには複数の関連パッケージが含まれていることがあります。同じリポジトリから複数のパッケージを加えたい場合は、プロジェクトマニフェストに 2 つの別々のエントリーを追加する必要があります。

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository.git?path=/subfolder1",
    "com.mycompany.mypackage3": "https://github.example.com/myuser/myrepository.git?path=/subfolder2/subfolder3"
  }
}

ノート: 同じリポジトリを複数回指定すると、Package Manager が同じリポジトリを複数回複製するため、パフォーマンスの低下やネットワーク使用量の増加につながります。

リビジョンとパスの同時指定

Unity がサポートする任意の Git プロトコルでパスとリビジョンを指定できます。ただし、path クエリパラメーターは、常にリビジョンアンカーの前に指定します。逆の順序では失敗します。以下は、正しい順序で使用する例です。

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3"
  }
}

ロックされた Git の依存関係

Package Manager の基本原則の 1 つは決定性です。プロジェクトを他のユーザーと共有する場合、Package Manager はパッケージの依存関係とバージョンの同じセットをインストールする必要があります。これには Git から入手するパッケージも含まれます。これを実現するために、Package Manager はロックファイル を使用して Git の依存関係のコミットハッシュを追跡します。

ブランチやタグにリビジョンが設定されている Git の依存関係を加えると、Package Manager は対応するコミットハッシュを取得してロックファイルに保存します。ブランチやタグは、時間の経過とともに Git リポジトリの異なるコミットを指すようになります。例えば、ブランチに、より新しいコミットが追加されるなどです。

ブランチやタグが指す別のコミットにパッケージを更新するには、Add package from git URL ボタンを使い、Git URL を入力します。新しいリクエストを送信する際、Package Manager はロックされたコミットハッシュを無視するので、同じ Git URL を使用できます。ただし、新しいリビジョン番号、タグ、ブランチなどを、代わりに リビジョン として指定することもできます。

あるいは、Client.Add C# API メソッドにその Git URL を指定してスクリプトを作成することもできます。

Git LFS のサポート

Package Manager は、Git LFS を使ってリポジトリによる Git 依存関係をサポートしています。Git LFS は、最小限の設定オーバーヘッドで動作するように設計され、HTTPS と SSH 認証の両方をサポートしています。

• HTTPS 認証の詳細については、HTTP/HTTPS プロトコルの使用 を参照してください。
• SSH 認証の詳細については、SSH プロトコルの使用 を参照してください。

ユーザーが認証を必要とする場合にリモートリポジトリにアクセスする権限を持つ有効な認証情報を持っていない場合には、LFS サーバーに保存されているファイルの取得は失敗します。

パッケージの作成者は、Git LFS クライアントが LFS サーバーの場所を見つけられるように、リポジトリ内の .lfsconfig 設定ファイルに URL を指定することができます。この方法は 2 つあります。

# Option 1: global setting
[lfs]
  url = ssh://git@HOSTNAME/path/to/repo.git

# Option 2: per-remote setting
[remote "origin"]
  lfsurl = ssh://git@HOSTNAME/path/to/repo.git

リポジトリに .lfsconfig ファイルが含まれている場合、パッケージの公開リリースに加えることを避けるために、.npmignore ファイル内に置くようにしてください。

Git の LFS キャッシュ

Unity 2021.2 では、オプションとして、Git ベースの依存関係をチェックアウトする際に Package Manager が使用する Git LFS キャッシュを有効にすることができます。これにより、リポジトリの異なるリビジョンをチェックアウトするたびに、同じファイルをダウンロードする必要がなくなります。

Package Manager の Git LFS キャッシュは、Git リポジトリの .git/lfs フォルダーの Git LFS キャッシュとは異なります。Package Manager は、プロジェクトキャッシュにパッケージをコピーした後、複製したリポジトリを保持しないため、デフォルトの Git キャッシュを使用できません。

Package Manager の Git LFS キャッシュを有効にするには、以下のいずれかのオプションを選択します。

• Git LFS キャッシュを有効にして、その場所として デフォルトのグローバルキャッシュルート の下の git-lfs サブフォルダーを使用するには、UPM_ENABLE_GIT_LFS_CACHE 環境変数に任意の (空ではない) 値を設定します。
• Git LFS キャッシュを有効にして、そのためのカスタムの保存場所を使うには、UPM_GIT_LFS_CACHE_PATH 環境変数にカスタムパスを設定します。この場所を設定すると、Git LFS キャッシュのオプションが自動的に有効になります。

グローバルキャッシュの環境変数設定の詳細については、グローバルキャッシュの場所のカスタマイズ を参照してください。

注意この最適化では、Git LFS を有効にしたパッケージを使用する場合、余分なディスクスペースが必要です。どちらにより多くの利点があるか、判断する必要があります。Git LFS ファイルのキャッシュはディスクスペースを消費しますが、同じファイルを再ダウンロードする手間を省くことができます。ただし、状況によってはキャッシュを活用できず、ファイルを再利用せずにディスクスペースを使ってしまうこともあります。例えば、Git の依存関係が、LFS で追跡されるさまざまなファイルコンテンツを参照するリビジョンに解決される可能性があります。以下は、そのシナリオ例です。

• 複数のプロジェクトの依存関係に異なる Git リビジョンを使用する
• パッケージを頻繁に更新して、さまざまな変更された LFS ファイルを含むリビジョンを作成する

追加リソース

• HTTPS Git URL を使用したプライベートリポジトリの使用
• SSH Git URL でのパスフレーズ保護された SSH キーの使用
• Git Large File Storage (LFS)
• Git サーバー - プロトコル
• Git URL からのインストール