Git の依存関係

When the Package Manager fetches a package from a Git repository, it adds the package locally to your project. This allows you to test unpublished changes, but you can’t use it to contribute to that Git repository. To set up an existing local Git repository as a dependency in your project, use a path to your local Git repository instead.

Note: You can’t specify Git dependencies in a package.json file because the Package Manager doesn’t support Git dependencies between packages. It supports Git dependencies only for projects, so you can declare Git dependencies only in the project’s manifest.json file.

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

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

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

要件

To use Git dependencies in a project, make sure you installed the Git client (minimum version 2.14.0) on your computer and that you have added the Git executable path to the PATH system environment variable.

Warning: Unity tested the Package Manager to work with Git 2.14.0 and above. Unity can’t guarantee the results if you use Git versions below 2.14.0.

If the repository tracks files with Git LFS, make sure the Git LFS client is also installed on your machine. If it’s not installed, the Package Manager can’t retrieve the files stored on the LFS server and instead checks out the LFS pointer files without any error or warning messages.

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

Git URL と拡張構文

The Package Manager supports all Git protocols, with the exception of local file paths. To specify a Git URL as a dependency, add the name of the package to add with a Git URL instead of the version number or local file path to the project manifest. For example, this demonstrates how to specify a remote Git using different protocols:

{
  "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.
  }
}

The Package Manager recognizes that a dependency formatted as a URL is a Git URL by looking for the .git file extension at the end of the repository path. Some Git repository hosting services don’t support URLs with this extension while others enforce it. For this reason, the Git dependency syntax allows you to omit the extension if you use the GIT protocol, or if you add a special git+ prefix to the HTTP/HTTPS, SSH, or FILE URL.

Note: The git+ prefix is a special marker in the manifest.json file that indicates that the dependency is Git based. The Package Manages doesn’t pass it to Git when cloning the repository.

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

You can also use extended syntax for Git dependencies:

• If the package you want isn’t at the root of the repository, you can specify a path to a package’s subfolder in the repository. This is necessary only if the package you want isn’t at the root of the repository. For example, the string ?path=/folder1/folder2 in:

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

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

• You can specify a Git revision, which can be a tag, branch name, or a specific commit hash to lock onto. This ensures that the Package Manager always loads that exact revision. If you don’t specify a revision, the Package Manager clones the repository at the default branch and latest commit and locks onto that revision. For example, the string #v2.0.0 in:

  "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"
  }
}

If your Git server doesn’t support the .git extension, you can add the special git+ prefix, with or without the extension:

{
  "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 を直接コピーアンドペーストできるからです。

If the repository isn’t publicly accessible and you are using HTTPS, the repository server fails to authenticate you because you can’t interact with the server to provide your credentials. In this case, the Editor notifies you that authentication failed.

To work around these authentication issues, you can either use a Git credentials helper to authenticate beforehand, or use the SSH protocol instead. If you set up and configure an SSH key pair with the Git repository hosting service, the Package Manager can authenticate the request seamlessly on your behalf.

#SSH プロトコルの使用

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

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

If your Git server doesn’t support the .git extension, you can add the special git+ prefix, with or without the extension:

{
  "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 プロトコルの使用

The Package Manager doesn’t recognize Git URLs with the file: prefix as Git dependencies unless they’re properly formatted. This means you must use either the git+file: protocol, or the .git suffix with the file: protocol:

{
  "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"
  }
}

The revision can be any tag, branch or commit hash. You must provide a full commit hash. Unity doesn’t support shortened SHA–1 hashes. This table shows examples for specifying revisions:

構文	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"

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

If you specify a repository using the Git URL syntax, the Package Manager assumes that the package must be at the root of the repository. However, some packages aren’t located at the root level of their repository, and some repositories contain more than one package.

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

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

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

In this case, the Package Manager registers the package located in the specified repository subfolder and disregards the rest of the repository.

リポジトリには複数の関連パッケージが含まれていることがあります。同じリポジトリから複数のパッケージを加えたい場合は、プロジェクトマニフェストに 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 の依存関係

One of the core principles of the Package Manager is determinism. If you share your project with other users, the Package Manager should install the same set of package dependencies and versions, and that includes packages that it fetches from Git. To achieve this, the Package Manager tracks commit hashes of Git dependencies by using a lock file.

ブランチやタグにリビジョンが設定されている 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 のサポート

The Package Manager supports Git dependencies with repositories using Git LFS. Since Git LFS is designed to work with minimal configuration overhead, it supports both HTTPS and SSH authentication:

• For information about HTTPS authentication, see Using the HTTP/HTTPS protocol.
• For information about SSH authentication, see Using the SSH protocol.

Retrieval of files stored on the LFS server fails if users need authentication and don’t 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 キャッシュ

As of Unity 2021.2, you can optionally enable a Git LFS cache for the Package Manager to use when checking out Git-based dependencies. This avoids having to download the same file every time you check out a different revision of the repository.

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.

To enable the Git LFS cache for the Package Manager, choose one of the following options:

• 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 Customize the global cache location.

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 you from downloading the same files again. However, some situations can’t make use of the cache and use up disk space without reusing the files. For example, your Git dependencies might resolve to revisions that reference different LFS-tracked file content, such as these scenarios:

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

その他の参考資料

• Git Large File Storage (LFS)
• Git on the Server - The Protocols
• Installing from a Git URL