Git の依存関係
Package Manager は、Git のリポジトリからパッケージを取得すると、プロジェクトへローカルにパッケージを追加します。これにより、公開されていない変更をテストすることができますが、Git リポジトリへのコントリビュートには使用できません。既存のローカル Git リポジトリをプロジェクトの依存関係として設定するには、代わりに ローカル Git リポジトリへのパス を使用します。
ノート: package.json ファイルで Git 依存関係を指定することはできません。Package Manager はパッケージ間の Git 依存関係をサポートしていないからです。Package Manager は、プロジェクトの Git 依存関係のみをサポートしています。そのため、プロジェクトの manifest.json ファイルでのみ、Git の依存関係を宣言することができます。
Tip: If you want to update your Git dependency to a specific version (revision) from the repository, refer to Locked Git dependencies.
このセクションでは、以下のトピックについて説明します。
要件
プロジェクトで 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 ポインターファイルをチェックアウトします。
You can use the Package Manager window to install a package directly from a Git repository. For more information, refer to Installing from a 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 の依存関係の構文では拡張子を省略することができます。
Note: The git+ prefix is a special marker in the manifest.json file that indicates that the dependency is Git based. The Package Manager doesn’t pass it to Git when cloning the repository.
For more information about the format of Git-supported URLs, refer to the documentation for the git clone command. For an overview of the difference between the protocols that Git uses, refer to the Git documentation for using protocols.
Git の依存関係に拡張構文を使うこともできます。
-
目的のパッケージがリポジトリのルートにない場合、リポジトリ内のパッケージのサブフォルダーへのパスを指定できます。これは、必要なパッケージがリポジトリのルートにない場合にのみ必要です。例えば、
?path=/folder1/folder2という文字列の場合は以下の通りです。"https://github.example.com/myuser/myrepository.git?path=/folder1/folder2"For more information, refer to Specifying a package in a subfolder.
-
ロックする Git リビジョン (タグ、ブランチ名、特定のコミットハッシュなど) を指定できます。これにより、Package Manager は常にその正確なリビジョンをロードできます。リビジョンを指定しない場合、Package Manager はデフォルトのブランチと最新のコミットでリポジトリをクローンし、そのリビジョンを追跡します。例えば、
#v2.0.0という文字列の場合は以下の通りです。"https://github.example.com/myuser/myrepository.git#v2.0.0"For more information, refer to Targeting a specific revision.
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"
}
}
Note: Alternatively, you can use the GIT protocol instead of the git+ prefix. For more information, refer to Using the GIT protocol.
リポジトリが一般に公開されている場合、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"
}
}
Note: Alternatively, you can use the GIT protocol instead of the git+ prefix. For more information, refer to Using the GIT protocol.
また、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での認証
If you want to use the SSH protocol, you need to set up SSH keys outside of Unity. For more information on setting up authentication for a specific host, refer to the help pages for Bitbucket, GitLab, and GitHub.
Note: If you encrypted your SSH key with a passphrase, the Package Manager can’t retrieve the package, because it doesn’t provide a way to enter the passphrase in a terminal or command line. In this case, the Editor notifies you that authentication failed. For help with using the ssh-agent for authentication, refer to Solutions for 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"
}
}
Note: Alternatively, you can use the GIT protocol instead of the git+ prefix. For more information, refer to Using the GIT protocol.
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 リポジトリの異なるコミットを指すようになります。たとえば、ブランチに、より新しいコミットが追加されるなどです。
To update the package to a different commit that a branch or tag points to, use the Install package from git URL button and enter a Git URL. You can use the same Git URL, because the Package Manager ignores the locked commit hash when you submit a new request. However, you can also specify a new revision number, tag, or branch as a revision instead.
あるいは、Client.Add C# API メソッドにその Git URL を指定してスクリプトを作成することもできます。
Git LFS のサポート
Package Manager は、Git LFS による Git 依存関係をサポートします。Git LFS は、最小限の設定オーバーヘッドで動作するように設計されているため、HTTPS と SSH 認証の両方をサポートします。
- For information about HTTPS authentication, refer to Using the HTTP/HTTPS protocol.
- For information about SSH authentication, refer to Using the SSH protocol.
ユーザーが認証を必要とし、リモートリポジトリへのアクセス許可を持つ有効なクレデンシャルを持たない場合、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 キャッシュを有効にすることができます。これにより、リポジトリの異なるリビジョンをチェックアウトするたびに同じファイルをダウンロードする必要がなくなります。
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 it copies packages 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 setting environment variables for the global cache, refer to Customize the global cache.
ノート: この最適化は、Git LFS 対応のパッケージを使用する際により多くのディスクスペースを必要とします。どちらのメリットが大きいかを判断する必要があります。Git LFS ファイルのキャッシュはディスクスペースを消費しますが、同じファイルを再ダウンロードする手間を省くことができます。ただし、状況によってはキャッシュを活用できず、ファイルを再利用せずにディスクスペースを使ってしまうこともあります。例えば、Git の依存関係が、LFS で追跡されるさまざまなファイルコンテンツを参照するリビジョンに解決される可能性があります。以下は、そのシナリオ例です。
- 複数のプロジェクトの依存関係に異なる Git リビジョンを使用する
- パッケージを頻繁に更新して、さまざまな変更された LFS ファイルを含むリビジョンを作成する