Git の依存関係
Package Manager は、Git のリポジトリからパッケージを取得すると、プロジェクトへローカルにパッケージを追加します。これにより、公開されていない変更を簡単にテストすることができますが、Git リポジトリへのコントリビュートには使用できません。既存のローカル Git リポジトリをプロジェクトの依存関係として設定するには、代わりに ローカル Git リポジトリへのパス を使用します。
package.json ファイルで Git 依存関係を指定することはできません。Package Manager はパッケージ間の Git 依存関係をサポートしていないからです。Package Manager は、プロジェクトの Git 依存関係のみをサポートしています。そのため、プロジェクトの manifest.json ファイルでのみ、Git の依存関係を宣言することができます。
ヒント: Git の依存関係をリポジトリの特定のバージョン (リビジョン) に更新したい場合は、ロックされた Git 依存関係 を参照してください。
このセクションでは、以下のトピックについて説明します。
要件
プロジェクトで Git の依存関係を使用するには、Git クライアント (最低バージョン 2.14.0) がマシンにインストールされており、Git の実行パスが PATH システム環境変数に追加されていることを確認してください。
注意: Package Manager は Git 2.14.0 以上で動作するようにテストされています。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 に特別な git+ のプレフィックスを加える場合には、Git の依存関係の構文では拡張子を省略することができます。
ノート: git+ プレフィックスは、manifest.json ファイル内の特別なマーカーで、依存関係が Git ベースであることを示します。Package Manager は、リポジトリのクローンを作成する際に、このプレフィックスを Git に渡しません。
Git がサポートする URL の形式に関する情報は、Git クローン コマンドを参照してください。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"詳しくは、特定のリビジョンを対象とする を参照してください。
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 認証ヘルパー を使って事前に認証するか、代わりに 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-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+ プレフィックスを必要とせず、サポートもしません。
特定のリビジョンをターゲットにする
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” には、任意のタグ、ブランチ、コミットハッシュを指定できます。この表は、リビジョンを指定する例です。
| 構文 | 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 が同じリポジトリを複数回クローンするため、パフォーマンスの低下やネットワーク使用量の増加につながります。
パスとリビジョンを同時に使う
path クエリパラメーターは、常にリビジョンアンカー (#) の前にあります。逆の順序では失敗します。以下は、正しい順序で使用する例です。
{
"dependencies": {
"com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3"
}
}
ロックされた Git の依存関係
Package Manager の基本原則のひとつは、決定論です。プロジェクトを他のユーザーと共有する場合、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 認証 の両方をサポートしています。ユーザーが認証を必要とする場合にリモートリポジトリにアクセス権限を持つ有効な認証情報を持っていない場合には、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 キャッシュ
デフォルトでは、Git LFS クライアントは、LFS サーバーからダウンロードしたファイルを、Git リポジトリの .git/lfs フォルダーにキャッシュします。これにより、リポジトリの異なるリビジョンをチェックアウトするたびに、同じファイルをダウンロードする必要がなくなります。ただし、Package Manager は、パッケージがプロジェクトキャッシュにコピーされた後、クローンされたリポジトリを維持しないため、Git の依存関係に対してこのキャッシュを使用することはできません。
Unity 2021.2 では、オプションとして、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 ファイルを含むリビジョンを作成する