내장 종속성

로컬 폴더 또는 타르볼 경로

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 및 확장 구문
잠긴 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 및 확장 구문

패키지 관리자는 로컬 파일 경로를 제외하고 모든 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.
  }
}

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

자세한 내용은 하위 폴더에 패키지 지정을 참조하십시오.
태그, 브랜치 이름 또는 잠글 특정 커밋 해시가 될 수 있는 Git 리비전을 지정할 수 있습니다. 이렇게 하면 패키지 관리자가 항상 정확한 리비전을 로드합니다. 리비전을 지정하지 않으면 패키지 관리자가 기본 브랜치와 최신 커밋에서 저장소를 복제합니다. 다음에서 #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"
  }
}

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 프로토콜 사용을 참조하십시오.

패키지 관리자가 항상 Git 종속성으로 인식하는 SCP와 유사한 짧은 표기를 사용할 수도 있습니다.

{
  "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를 통한 인증

SSH 프로토콜을 사용하려면 Unity 외부에서 SSH 키를 설정해야 합니다. 특정 호스트의 인증 설정에 대한 자세한 내용은 Bitbucket, GitLab 및 GitHub에 대한 도움말 페이지를 참조하십시오.

참고: SSH 키를 패스프레이즈로 암호화한 경우 패키지 관리자는 터미널 또는 커맨드 라인에 패스프레이즈를 입력하는 방법을 제공하지 않으므로 패키지를 검색할 수 없습니다. 이 경우 에디터는 인증에 실패했음을 알려줍니다. 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 프로토콜 사용을 참조하십시오.

대신에 패키지 관리자는 다른 모든 구문을 로컬 경로로 해석합니다.

GIT 프로토콜 사용

패키지 관리자는 .git 경로 접미사를 포함하거나 포함하지 않은 git: 프로토콜을 인식합니다.

{
  "dependencies": {
    "com.mycompany.mypackage1": "git://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git://github.example.com/myuser/myrepository2"
  }
}

GIT 프로토콜은 git+ 접두사를 필요로 하거나 지원하지 않습니다.

특정 리비전 타게팅

패키지 관리자가 복제할 특정 리비전을 선언하려면 URL 끝에 숫자 기호(#) 접두사가 붙은 리비전을 추가하십시오.

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git#revision",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2#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"`

저장소의 하위 폴더에 패키지 지정

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

참고: 동일한 저장소를 여러 번 지정하면 패키지 관리자가 동일한 저장소를 여러 번 복제하므로 성능이 저하되고 네트워크 사용량이 증가합니다.

경로와 리비전을 동시에 사용

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 종속성을 추가하면 패키지 관리자는 해당 커밋 해시를 페치한 후 잠금 파일에 저장합니다. 시간이 지남에 따라 브랜치와 태그는 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, 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.

패키지 작성자는 저장소의 .lfsconfig 설정 파일에 URL을 제공하여 Git LFS 클라이언트가 LFS 서버를 찾도록 도울 수 있습니다. 이를 수행하는 데는 다음의 두 가지 방법이 있습니다.

# 옵션 1: 전역 설정
[lfs]
  url = ssh://git@HOSTNAME/path/to/repo.git

# 옵션 2: 원격당 설정
[remote "origin"]
  lfsurl = ssh://git@HOSTNAME/path/to/repo.git

저장소에 .lfsconfig 파일이 있는 경우 패키지의 퍼블리시된 릴리스에 포함되지 않도록 .npmignore 파일에 포함해야 합니다.

Git LFS 캐시

Unity 2021.2부터 패키지 관리자가 Git 기반 종속성을 체크아웃할 때 사용할 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.

패키지 관리자에 대해 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 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 파일을 포함하는 리비전으로 패키지를 자주 업데이트

추가 리소스

내장 종속성

로컬 폴더 또는 타르볼 경로

"Unity"、Unity 徽标及其他 Unity 商标是 Unity Technologies 或其附属机构在美国及其他地区的商标或注册商标。其他名称或品牌是其各自所有者的商标。

公安部备案号:

31010902002961

法律条款隐私政策 Cookies

매뉴얼

Git 종속성

요구 사항

Git URL 및 확장 구문

HTTP/HTTPS 프로토콜 사용

SSH 프로토콜 사용

Windows에서 PuTTY 사용

SSH를 통한 인증

FILE 프로토콜 사용

GIT 프로토콜 사용

특정 리비전 타게팅

저장소의 하위 폴더에 패키지 지정

경로와 리비전을 동시에 사용

잠긴 Git 종속성

Git LFS 지원

Git LFS 캐시

추가 리소스