Git の依存関係
Package Manager は、Git のリポジトリからパッケージを取得すると、プロジェクトへローカルにパッケージを追加します。これにより、公開されていない変更を簡単にテストすることができますが、Git リポジトリへのコントリビュートには使用できません。既存のローカル Git リポジトリをプロジェクトの依存関係として設定するには、代わりに ローカル Git リポジトリへのパス を使用します。
Note: You cannot specify Git dependencies in a package.json file because the Package Manager does not support Git dependencies between packages. It only supports Git dependencies for projects, so you can only declare Git dependencies in the project’s manifest.json file.
ヒント: 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” には、任意のタグ、ブランチ、コミットハッシュを指定できます。完全なコミットハッシュを提供する必要があります。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 が同じリポジトリを複数回クローンするため、パフォーマンスの低下やネットワーク使用量の増加につながります。
パスとリビジョンを同時に使う
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 のサポート
The Package Manager supports Git dependencies with repositories using Git LFS. Since Git LFS has been designed to work with minimal configuration overhead, it supports both HTTPS and SSH authentication. Retrieval of files stored on the LFS server fails if users need to be authenticated and do not have valid credentials with permission to access the remote repository.
パッケージの作成者は、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 キャッシュを有効にすることができます。これにより、リポジトリの異なるリビジョンをチェックアウトするたびに同じファイルをダウンロードする必要がなくなります。
The Git LFS cache for the Package Manager is different from the Git LFS cache in the .git/lfs folder of your Git repository. The Package Manager can’t use the default Git cache because it doesn’t keep cloned repositories after the packages have been copied to the project cache.
Package Manager の Git LFS キャッシュを有効にするには、以下のオプションのいずれかを選択します。
- Git LFS キャッシュを有効にして、その場所として デフォルトのグローバルキャッシュルート の下の
git-lfsサブフォルダーを使用するには、UPM_ENABLE_GIT_LFS_CACHE環境変数に任意の (空ではない) 値を設定します。 - Git LFS キャッシュを有効にして、そのためのカスタムの保存場所を使うには、
UPM_GIT_LFS_CACHE_PATH環境変数にカスタムパスを設定します。この場所を設定すると、Git LFS キャッシュのオプションが自動的に有効になります。
For more information about how to set environment variables for the global cache, see Customizing the shared cache locations.
Note: This optimization requires extra disk space when using Git LFS-enabled packages. You need to decide which is the greater benefit: Git LFS file caching costs disk space but saves on re-downloading the same files. However, some situations can’t make use of the cache and use up disk space without re-using the files. For example, your Git dependencies might resolve to revisions that reference different LFS-tracked file content, such as these scenarios:
- 複数のプロジェクトの依存関係に異なる Git リビジョンを使用する
- パッケージを頻繁に更新して、さまざまな変更された LFS ファイルを含むリビジョンを作成する