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.
Tip: If you want to update your Git dependency to a specific version (revision) from the repository, refer to Locked Git dependencies.
此部分包含以下主题：
要求
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.
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 和扩展语法
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 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.
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/folder2in:"https://github.example.com/myuser/myrepository.git?path=/folder1/folder2"。For more information, refer to Specifying a package in a subfolder.
-
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.0in:"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"
}
}
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"
}
}
Note: Alternatively, you can use the GIT protocol instead of the git+ prefix. For more information, refer to Using the GIT protocol.
如果代码仓库可公开访问，则 HTTPS 是用于与用户共享 Git URL 的推荐方案，因为可以直接从 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"
}
}
Note: Alternatively, you can use the GIT protocol instead of the git+ prefix. For more information, refer to Using the GIT protocol.
还可以使用类似 SCP 的速记，Package Manager 会始终将它识别为 Git 依赖关系：
{
"dependencies": {
"com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git"
}
}
在 Windows 上使用 PuTTY
当您使用 SSH 进行身份验证时，Git 会使用默认位置的密钥。但是，如果您在 Windows 上使用 PuTTY 作为 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 协议
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"
}
}
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 协议
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 末尾添加以数字符号 (#) 作为前缀的修订版本：
{
"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.
有时一个代码仓库包含多个相关包。如果要从同一个代码仓库添加多个包，则必须向项目清单添加两个单独的条目：
{
"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.
或者，可以使用带有该 Git URL 的 Client.Add C# API 方法创建脚本。
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, refer to Using the HTTP/HTTPS protocol.
- For information about SSH authentication, refer to 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.
包作者可以通过在代码仓库中的 .lfsconfig 配置文件中提供 URL 来帮助 Git LFS 客户端定位 LFS 服务器。有两种方式可以做到这一点：
# 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 setting environment variables for the global cache, refer to Customize the global cache.
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 文件的修订版本