Git 종속성
패키지 관리자는 Git 저장소에서 패키지를 페치할 때 패키지를 로컬로 프로젝트에 추가합니다. 이렇게 하면 퍼블리시되지 않은 변경 사항을 쉽게 테스트할 수 있지만 해당 Git 저장소에 기여하는 데는 사용할 수 없습니다. 기존 로컬 Git 저장소를 프로젝트의 종속성으로 설정하려면 로컬 Git 저장소 경로를 대신 사용하십시오.
package.json 파일에는 Git 종속성을 지정할 수 없습니다. 패키지 관리자는 패키지 간 Git 종속성을 지원하지 않기 때문입니다. 프로젝트에 대한 Git 종속성만 지원하므로 프로젝트의 manifest.json 파일에서 Git 종속성만 선언할 수 있습니다.
팁: Git 종속성을 저장소에서 특정 버전(리비전)으로 업데이트하려는 경우 잠긴 Git 종속성을 참조하십시오.
이 섹션에서는 다음의 항목을 다룹니다.
요구 사항
프로젝트에서 Git 종속성을 사용하려면 컴퓨터에 Git 클라이언트(최소 2.14.0 버전)를 설치하고 Git 실행 가능 경로를 PATH 시스템 환경 변수에 추가해야 합니다.
경고: 패키지 관리자는 Git 2.14.0 이상에서 작동하도록 테스트되었습니다. Unity는 2.14.0 미만의 Git 버전을 사용하는 경우 결과를 보장하지 않습니다.
저장소가 Git LFS를 사용하여 파일을 추적하는 경우 Git LFS 클라이언트를 컴퓨터에도 설치해야 합니다. 그러지 않으면 패키지 관리자가 LFS 서버에 저장된 파일을 검색해서 가져오지 못하고, 대신에 오류 또는 경고 메시지 없이 LFS 포인터 파일을 체크아웃합니다.
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.
}
}
패키지 관리자는 저장소 경로의 끝에서 .git 파일 확장자를 찾아 URL로 포맷이 지정된 종속성이 Git URL이라고 인식합니다. 일부 Git 저장소 호스팅 서비스는 이 확장자를 사용하는 URL을 지원하지 않지만 다른 서비스들은 이를 적용합니다. 이러한 이유로 GIT 프로토콜을 사용하거나, 또는 특수한 git+ 접두사를 HTTP/HTTPS, SSH 또는 FILE URL에 추가하는 경우 Git 종속성 구문을 사용하면 확장자를 생략할 수 있습니다.
참고: git+ 접두사는 종속성이 Git 기반임을 나타내는 manifest.json 파일의 특수 마커입니다. 패키지 관리자는 저장소를 복제할 때 Git에 이 접두사를 전달하지 않습니다.
Git 지원 URL 포맷에 대한 자세한 내용은 Git 복제 커맨드 문서를 참조하십시오. 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"자세한 내용은 특정 리비전 타게팅을 참조하십시오.
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을 복사하여 붙여 넣을 수 있기 때문입니다.
저장소에 공개적으로 액세스할 수 없고 HTTPS를 사용하는 경우 자격 증명을 제공하기 위해 서버와 상호작용할 수 없기 때문에 저장소 서버가 사용자 인증에 실패합니다. 이 경우 에디터는 인증에 실패했음을 알려줍니다.
이러한 인증 문제를 해결하기 위해 Git 자격 증명 도우미를 사용하여 미리 인증하거나 SSH 프로토콜을 대신 사용할 수 있습니다. Git 저장소 호스팅 서비스를 사용하여 SSH 키 쌍을 설정하고 구성하면 패키지 관리자가 사용자를 대신하여 요청을 원활하게 인증할 수 있습니다.
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"
}
}
참고: 또는 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 프로토콜 사용
올바른 포맷을 지정하지 않으면 패키지 관리자는 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"
}
}
참고: 또는 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"
}
}
리비전은 태그, 브랜치 또는 커밋 해시일 수 있습니다. 이 표에는 리비전 지정에 대한 예시가 나와 있습니다.
| 구문: | 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 구문을 사용하여 저장소를 지정하는 경우 패키지 관리자는 패키지가 저장소의 루트에 있다고 가정합니다. 하지만 일부 패키지는 저장소의 루트 수준에 있지 않으며, 일부 저장소에는 두 개 이상의 패키지가 들어 있습니다.
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"
}
}
참고: 동일한 저장소를 여러 번 지정하면 패키지 관리자가 동일한 저장소를 여러 번 복제하므로 성능이 저하되고 네트워크 사용량이 증가합니다.
경로와 리비전을 동시에 사용
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 LFS를 사용하는 저장소에서 Git 종속성을 지원합니다. Git LFS는 최소한의 설정 오버헤드로 작동하도록 설계되었으므로 HTTPS 및 SSH 인증을 모두 지원합니다. 사용자가 인증을 받아야 하고 원격 저장소에 대한 액세스 권한이 있는 유효한 자격 증명이 없으면 LFS 서버에 저장된 파일을 검색해서 가져오지 못합니다.
패키지 작성자는 저장소의 .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 캐시
기본적으로 Git LFS 클라이언트는 Git 저장소의 .git/lfs 폴더 안에 있는 LFS 서버에서 다운로드한 파일을 캐싱합니다. 이렇게 하면 저장소의 다른 리비전을 확인할 때마다 동일한 파일을 다운로드하지 않아도 됩니다. 하지만 패키지 관리자는 패키지가 프로젝트 캐시에 복사된 후 복제된 저장소를 유지하지 않기 때문에 Git 종속성에 이 캐시를 사용할 수 없습니다.
Unity 2021.2부터 패키지 관리자가 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 파일을 포함하는 리비전으로 패키지를 자주 업데이트