기술 자료

Unity 엔진

Unity 엔진

Git 종속성 소개

Git 저장소에서 패키지를 가져오는 데 발생하는 종속성에 대해 알아봅니다. Git 저장소에서 패키지를 가져오는 데 사용할 수 있는 프로토콜과 확장 구문을 알아보십시오.
읽는 시간 10분최근 업데이트: 9일 전

패키지 관리자 Git 저장소에서 패키지를 가져오면 패키지를 프로젝트에 로컬로 추가합니다. 이렇게 하면 퍼블리시되지 않은 변경 사항을 테스트할 수 있지만 이를 사용하여 해당 Git 저장소에 기여할 수는 없습니다. 프로젝트에서 기존 로컬 Git 저장소를 종속성으로 설정하려면 대신 로컬 Git 저장소 경로를 사용하십시오.
참고
패키지 관리자가 패키지 간 Git 종속성을 지원하지 않으므로 package.json 파일에서 Git 종속성을 지정할 수 없습니다. 프로젝트에 대해서만 Git 종속성을 지원하므로 프로젝트의 manifest.json 파일에서만 Git 종속성을 선언할 수 있습니다.
팁
저장소에서 Git 종속성을 특정 버전(리비전)으로 업데이트하려면 잠긴 Git 종속성을 참조하십시오.
이 섹션에는 다음 항목이 포함되어 있습니다.

요구 사항

프로젝트에서 Git 종속성을 사용하려면 컴퓨터에 Git 클라이언트(최소 버전 2.14.0)를 설치하고 Git 실행 파일 경로를 PATH 시스템 환경 변수에 추가했는지 확인합니다.
경고
Unity Git 2.14.0 이상에서 패키지 관리자 테스트했습니다. 2.14.0 미만의 Git 버전을 사용하는 경우 Unity 결과를 보장할 수 없습니다.
저장소가 파일을 Git LFS로 추적하는 경우 컴퓨터에 Git LFS 클라이언트가 설치되어 있는지 확인하십시오. 설치되지 않은 경우 패키지 관리자는 LFS 서버에 저장된 파일을 검색할 수 없음으로 오류나 경고 메시지 없이 LFS 포인터 파일을 체크아웃합니다.
패키지 관리자 창을 사용하여 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. }}
패키지 관리자는 저장소 경로 끝에 있는
.git
파일 확장자를 검색하여 URL 형식이 Git URL임을 인식합니다. 일부 Git 저장소 호스팅 서비스는 이 확장자가 포함된 URL을 지원하지 않으며, 다른 서비스는 이를 적용합니다. 이러한 이유로 Git 종속성 구문에서는 Git 프로토콜을 사용하거나, HTTP/HTTPS, SSH 또는 FILE URL에 특별한
git+
접두사를 추가하는 경우 확장자를 생략할 수 있습니다.
참고
git+
접두사는 종속성이 Git 기반임을 나타내는
manifest.json
파일의 특수 마커입니다. 패키지 관리자 저장소를 복제할 때 Git 전달하지 않습니다.
Git 지원 URL의 포맷에 대한 자세한 내용은 Git clone 명령에 대한 문서를 참조하십시오. Git에서 사용하는 프로토콜 간의 차이점에 대한 개요는 프로토콜 사용에 대한 Git 문서를 참조하십시오.
Git 종속성에도 확장 구문을 사용할 수 있습니다.
  • 원하는 패키지가 저장소의 루트에 없는 경우 저장소의 패키지 하위 폴더 경로를 지정할 수 있습니다. 원하는 패키지가 저장소의 루트에 없는 경우에만 필요합니다. 예를 들어 다음의 문자열
    ?path=/folder1/folder2
    :
    "https://github.example.com/myuser/myrepository.git?path=/folder1/folder2"
    .
    자세한 내용은 하위 폴더에서 패키지 지정을 참고하십시오.
  • 잠금을 위한 태그, 브랜치 이름 또는 특정 커밋 해시일 수 있는 Git 리비전을 지정할 수 있습니다. 그러면 패키지 관리자 항상 정확한 리비전을 로드합니다. 리비전을 지정하지 않으면 패키지 관리자 기본 브랜치와 최신 커밋의 저장소를 복제하고 해당 리비전을 잠급니다. 예를 들어 다음의 문자열
    #v2.0.0
    :
    "https://github.example.com/myuser/myrepository.git#v2.0.0"
    자세한 내용은 Git 버전 지정을 참조하십시오.

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을 공유하는 데 권장되는 방식입니다.

Copy the URL from the package repository

저장소에 공개적으로 액세스할 수 없고 HTTPS를 사용 중인 경우 자격 증명을 제공하기 위해 서버와 상호 작용할 수 없기 때문에 저장소 서버가 인증하지 못합니다. 이 경우 에디터는 Authentication 실패했음을 알립니다.
이러한 Authentication 문제를 해결하려면 다음 중 하나를 수행하십시오.

SSH 프로토콜 사용

SSH 프로토콜을 전체 URL 함께 사용할 수 있습니다.
{ "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 프로토콜 사용을 참조하십시오.
또한 패키지 관리자 항상 Git 종속성으로 인식하는 SCP와 유사한 짧은 표기를 사용할 수도 있습니다.
{ "dependencies": { "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git" }}

Windows PuTTY 사용

SSH를 사용하여 인증할 때 Git 기본 위치의 키를 사용합니다. 그러나 Windows에서 SSH 클라이언트로 PuTTY를 사용하는 경우
GIT_SSH
환경 변수를 구성하여
plink.exe
를 가리키도록 해야 합니다.

SSH로 인증

SSH 프로토콜을 사용하려면 Unity 외부에서 SSH 키를 설정해야 합니다. 특정 호스트에 대한 Authentication 설정에 대한 자세한 내용은 Bitbucket, GitLab 및 GitHub에 대한 도움말 페이지를 참조하십시오.
참고
SSH 키를 암호화한 경우 패키지 관리자 터미널이나 커맨드 라인 암호를 입력할 수 있는 방법을 제공하지 않으므로 패키지를 검색해서 가져올 수 없습니다. 이 경우 에디터는 Authentication 실패했음을 알립니다. Authentication 에이전트 사용에 대한 자세한 내용은 SSH Git URL과 함께 비밀번호 보호 SSH 키 사용을 참조하십시오. Authentication에 ssh-agent를 사용하는 방법에 대한 자세한 내용은 SSH 솔루션을 참조하십시오.

FILE 프로토콜 사용

패키지 관리자는 올바르게 포맷되지 않는 한
file:
접두사가 있는 Git URL을 Git 종속성으로 인식하지 않습니다. 즉,
git+file:
프로토콜 또는
.git
접미사를
file:
프로토콜과 함께 사용해야 합니다.
{ "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+
접두사를 필요로 하거나 지원하지 않습니다.

확장 구문

확장 구문을 사용하여 특정 Git 리비전이나 하위 폴더의 패키지 또는 둘 다를 식별할 수 있습니다.
확장 구문은 Unity 지원하는 모든 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#tag-pointing-to-package-version"
커밋 해시
"https://github.example.com/myuser/myrepository.git#9e72f9d5a6a3dadc38d813d8399e1b0e86781a49"

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

Git URL 구문을 사용하여 저장소를 지정하는 경우 패키지 관리자 패키지가 저장소의 루트에 있어야 한다고 가정합니다. 하지만 일부 패키지는 저장소의 루트 수준에 없으며, 일부 저장소에는 두 개 이상의 패키지가 포함되어 있습니다.
Git URL의
path
쿼리 파라미터를 사용하여 패키지를 찾을 위치를 패키지 관리자에게 알릴 수 있습니다. 지정하는 경로는 저장소의 루트와 관련되어야 하며 지정하는 하위 폴더에는 패키지 매니페스트(
package.json
파일)가 포함되어야 합니다.
Git 종속성에 대한 저장소 하위 폴더를 지정하려면 다음과 같이
path
쿼리 파라미터를 사용하십시오.
{ "dependencies": { "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/subfolder" }}
이 경우 패키지 관리자 지정된 저장소 하위 폴더에 있는 패키지를 등록하고 나머지 저장소를 무시합니다.
저장소에는 종종 여러 관련 패키지가 포함되어 있습니다. 동일한 저장소에서 두 개 이상의 패키지를 추가하려면 프로젝트 매니페스트에 두 개의 별도의 항목을 추가해야 합니다.
{ "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" }}
참고
동일한 저장소를 여러 번 지정하면 패키지 관리자 동일한 저장소를 여러 번 복제하여 성능 저하와 네트워크 사용량이 증가합니다.

리비전과 경로를 동시에 지정

Unity 지원하는 모든 Git 프로토콜로 경로와 리비전을 지정할 수 있습니다. 그러나
path
쿼리 파라미터는 항상 리비전 앵커 앞에 있습니다. 역순차가 실패합니다. 다음은 올바른 사용 순서의 예시입니다.
{ "dependencies": { "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3" }}

잠긴 Git 종속성

패키지 관리자 핵심 원리 중 하나는 결정론입니다. 프로젝트를 다른 사용자와 공유하는 경우 패키지 관리자는 동일한 패키지 종속성 및 버전을 설치해야 하며 여기에는 Git에서 가져온 패키지가 포함됩니다. 이를 위해 패키지 관리자는 잠금 파일을 사용하여 Git 종속성의 커밋 해시를 추적합니다.
브랜치 또는 태그에 리비전이 설정된 Git 종속성을 추가하면 패키지 관리자 해당 커밋 해시를 페치하여 잠금 파일에 저장합니다. 시간이 지남에 따라 브랜치와 태그는 Git 저장소의 다른 커밋을 가리킬 수 있습니다. 예를 들어 브랜치에 새로운 커밋이 추가될 수 있습니다.
패키지를 브랜치 또는 태그가 가리키는 다른 커밋으로 업데이트하려면 Git URL에서 패키지 설치 버튼을 사용하고 Git URL을 입력합니다. 새 요청을 제출할 때 패키지 관리자 잠긴 커밋 해시를 무시하므로 동일한 Git URL 사용할 수 있습니다. 하지만 새 리비전 번호, 태그 또는 브랜치를 대신 리비전으로 지정할 수도 있습니다.
또는 해당 Git URL을 사용하여 Client.Add C# API 메서드를 사용하여 스크립트를 만들 수도 있습니다.

Git LFS 지원

패키지 관리자는 Git Large File Storage(LFS)를 사용하는 저장소에서 Git 종속성을 지원합니다. 하지만 Unity 흐릿한 클론을 사용하므로 LFS로 추적된 파일은 항상 올바르게 페치되지 않습니다. 때때로 패키지는 실제 파일 콘텐츠 대신 플레이스홀더 포인터 파일을 임포트할 수 있습니다. 자세한 내용은 Git LFS 오류를 참조하십시오.
Git LFS는 최소한의 구성 오버헤드로 작동하도록 설계되었으므로 HTTPS와 SSH Authentication 모두 지원합니다.
사용자가 Authentication 필요하고 원격 저장소에 액세스할 권한이 있는 유효한 자격 증명이 없는 경우 LFS 서버에 저장된 파일을 가져오는 데 실패합니다.
패키지 작성자는 저장소의
.lfsconfig
구성 파일에 URL을 제공하여 Git LFS 클라이언트가 LFS 서버를 찾는 데 도움이 됩니다. 다음 두 가지 방법을 사용할 수 있습니다.
# Option 1: global setting##option-1:-global-setting[lfs] url = ssh://git@HOSTNAME/path/to/repo.git# Option 2: per-remote setting##option-2:-per-remote-setting[원격 "origin"] lfsurl = ssh://git@HOSTNAME/path/to/repo.git
저장소에
.lfsconfig
파일이 있는 경우 패키지의 퍼블리시된 릴리스에 포함되지 않도록
.npmignore
파일에 포함해야 합니다.

Git LFS 캐시

Unity 2021.2부터 Git 기반 종속성을 체크아웃할 때 패키지 관리자가 사용할 Git LFS 캐시를 선택적으로 활성화할 수 있습니다. 이렇게 하면 저장소의 다른 리비전을 체크아웃할 때마다 동일한 파일을 다운로드할 필요가 없습니다.
패키지 관리자의 Git LFS 캐시는 Git 저장소의
.git/lfs
폴더에 있는 Git LFS 캐시와 다릅니다. 패키지 관리자 프로젝트 캐시에 패키지를 복사한 후 복제된 저장소를 유지하지 않으므로 기본 Git 캐시를 사용할 수 없습니다.
패키지 관리자 대해 Git LFS 캐시를 활성화하려면 다음 옵션 중 하나를 선택합니다.
  • Git LFS 캐시를 활성화하고 기본 전역 캐시 루트 아래의
    git-lfs
    하위 폴더를 위치로 사용하려면
    UPM_ENABLE_GIT_LFS_CACHE
    환경 변수를 임의(비어 있음) 값으로 설정합니다.
  • Git LFS 캐시를 활성화하고 커스텀 위치를 사용하려면
    UPM_GIT_LFS_CACHE_PATH
    환경 변수를 커스텀 경로로 설정합니다. 위치를 설정하면 Git LFS 캐시 옵션이 자동으로 활성화됩니다.
전역 캐시에 대한 환경 변수 설정에 대한 자세한 내용은 전역 캐시 커스터마이즈를 참조하십시오.
참고
이 최적화는 Git LFS 지원 패키지를 사용할 때 추가 디스크 공간이 필요합니다. Git LFS 파일 캐싱이 디스크 공간을 소모하지만 동일한 파일을 다시 다운로드하는 것을 절약하는 큰 이점이 무엇인지 결정해야 합니다. 하지만 일부 상황에서는 파일을 재사용하지 않고 캐시를 사용하고 디스크 공간을 사용할 수 없습니다. 예를 들어 Git 종속성은 다음 시나리오와 같이 다른 LFS 추적 파일 콘텐츠를 참조하는 리비전으로 해결될 수 있습니다.
  • 여러 프로젝트에서 종속성에서 다른 Git 리비전 사용
  • 다양한 변경된 LFS 파일이 포함된 리비전으로 패키지를 자주 업데이트

추가 리소스