github에 유니티 프로젝트를 통째로 올렸다면: 올리지 말아야 할 Library 폴더

GitHub Desktop에서 유니티 프로젝트를 커밋하고 Push를 눌렀더니 github가 100.00 MB 제한을 넘었다며 거절합니다. 겨우 올렸더니 이번에는 팀원이 받은 프로젝트가 패키지 오류와 빠진 설정으로 열립니다. 두 증상은 달라 보여도 출발점이 같습니다. GitHub에 어느 폴더를 올리고 어느 폴더를 내 컴퓨터에 남기느냐입니다.

더 답답한 경우도 있습니다. 저장소를 만들 때 Git ignore를 Unity로 골랐는데도 Library 폴더가 그대로 올라가는 경우입니다. 공식 템플릿을 넣었는데 왜 걸러지지 않을까요? 이 글은 세 가지를 차례로 짚습니다. 올릴 폴더와 뺄 폴더, .gitignore가 Library를 놓치는 이유, 이미 올렸을 때 되돌리는 순서입니다. 기준은 Unity 6 매뉴얼과 GitHub 공식 문서이고, git 동작은 git 2.38로 같은 폴더 구조를 만들어 돌려 본 결과입니다.

• 1. github에 올릴 폴더는 셋
• 2. Library를 올리면 생기는 두 가지 일
• 3. .gitignore를 넣었는데도 Library가 올라가는 이유
• 4. 이미 올렸다면 되돌리는 순서
• 5. 제대로 걸러졌는지 확인하기

1. github에 올릴 유니티 폴더는 셋뿐입니다

유니티 프로젝트 폴더를 열면 Assets 말고도 여러 폴더가 보입니다. 이 폴더들은 두 종류로 나뉩니다. 내가 만든 원본과, 유니티가 그 원본으로 만들어 낸 결과물입니다.

후디니의 시뮬레이션 캐시를 떠올리면 쉽습니다. hip 파일과 소스가 있으면 캐시는 언제든 다시 구울 수 있습니다. 유니티의 Library가 바로 그 캐시입니다. Unity 6 매뉴얼은 Library를 가져온 에셋과 메타데이터의 로컬 캐시라고 설명합니다. 그리고 컴퓨터마다 고유한 작업 폴더이니 버전 관리에서 빼라고 적습니다. Library를 지우면 Unity는 다음에 프로젝트를 열 때 다시 만듭니다. 대신 모든 코드를 다시 컴파일하고 모든 에셋을 다시 가져오므로 시간이 꽤 걸립니다.

폴더	들어 있는 것	GitHub에
Assets	씬, 스크립트, 텍스처, 모델 같은 원본 에셋과 에셋마다 붙는 .meta 파일	올림
Packages	프로젝트가 쓰는 패키지 목록(manifest.json, packages-lock.json)	올림
ProjectSettings	빌드, 그래픽, 입력, 태그 같은 프로젝트 설정	올림
Library	가져온 에셋의 캐시, 설치된 패키지(PackageCache)	뺌
Temp	Unity를 닫을 때마다 비워지는 임시 데이터	뺌
Logs	임포트와 에디터 작업 로그	뺌
UserSettings	내 에디터 레이아웃 같은 개인 설정	뺌
Obj, Build, Builds	GitHub의 Unity 템플릿이 빼는 빌드 관련 폴더	뺌

Packages와 ProjectSettings는 크기가 작아서 빼먹기 쉽습니다. 하지만 manifest.json이 없으면 팀원의 Unity는 이 프로젝트가 어떤 패키지를 쓰는지 모릅니다. 그 패키지를 쓰는 스크립트에서 오류가 날 수 있습니다. ProjectSettings가 빠지면 태그, 레이어, 입력 설정이 기본값으로 열립니다. 팀원 쪽 프로젝트는 너무 많이 올려도 깨지고, 이 둘을 빼도 깨집니다. Unity는 packages-lock.json도 소스 관리에 넣으라고 권합니다. 그래야 다른 컴퓨터에서도 같은 패키지 버전이 풀립니다.

Assets 안의 .meta 파일도 원본입니다. 용량을 줄이려고 .gitignore에 *.meta나 *.png를 넣으라는 글이 보이는데, 그러면 팀원 쪽에서 에셋과 참조가 빠집니다. .meta는 에셋과 늘 함께 올립니다.

덧붙여, 클라우드 동기화 폴더에 프로젝트를 두고 함께 쓰는 방식은 Unity가 지원하지 않는다고 매뉴얼에 적혀 있습니다. 동기화 문제로 프로젝트가 손상될 수 있다는 이유입니다. 공유는 버전 관리로 합니다.

2. Library를 올리면 생기는 두 가지 일

첫째는 용량입니다. GitHub는 50MiB가 넘는 파일에는 경고를 띄우고, 100MiB가 넘는 파일은 아예 받지 않습니다. Library 안의 파일 하나가 이 선을 넘기도 합니다. Reddit의 Unity 커뮤니티에는 Library/PackageCache 안 Burst 패키지의 파일 하나가 106.20MB라서 push가 막혔다는 사례가 올라와 있습니다. 큰 파일이 없더라도 GitHub는 저장소를 1GB 아래로, 늦어도 5GB 아래로 유지하라고 권합니다.

이 단계에서 Git LFS부터 찾는 사람이 많습니다. LFS는 100MB를 넘는 원본 파일을 저장소에 두기 위한 장치입니다. 다시 만들 수 있는 캐시를 LFS로 올리면 쓸모없는 데이터를 계속 쌓을 뿐입니다. Assets 안의 원본 파일 자체가 100MB를 넘을 때만 LFS를 검토합니다.

둘째는 팀원 쪽입니다. Library는 Unity가 작업하는 동안 계속 고쳐 쓰는 폴더입니다. 매뉴얼을 보면 Library 안의 StateCache에는 Hierarchy 창과 Scene 뷰의 상태까지 들어 있습니다. 올려 두면 에디터를 쓰기만 해도 바뀌는 파일이 매번 커밋 대상이 됩니다. 두 사람이 같은 캐시 파일을 바꾸면 pull할 때 충돌이 납니다. 원본은 하나도 안 건드렸는데 충돌을 풀어야 하는 셈입니다.

그래서 Library는 빼야 합니다. 그런데 .gitignore로 분명히 뺐는데도 올라간다면, 무엇이 남았을까요?

3. .gitignore를 넣었는데도 Library가 올라가는 이유

GitHub Desktop(깃허브 데스크탑)에서 새 저장소를 만들 때 Git ignore 목록에서 Unity를 고르면 GitHub의 공식 Unity 템플릿이 .gitignore로 들어갑니다. 여기까지는 맞게 한 것입니다. 문제는 그다음에 생깁니다.

GitHub Desktop은 Local path 안에 저장소 이름으로 새 폴더를 만들고, .gitignore를 그 폴더 맨 위에 둡니다. 여기에 이미 만들어 둔 유니티 프로젝트 폴더를 통째로 끌어다 넣으면 구조가 이렇게 됩니다.

MyRepo/              ← 저장소 맨 위
├─ .gitignore        ← Unity 템플릿
└─ MyGame/           ← 통째로 넣은 유니티 프로젝트
   ├─ Assets/
   ├─ Packages/
   ├─ ProjectSettings/
   └─ Library/

Unity 템플릿의 줄은 /[Ll]ibrary/처럼 슬래시로 시작합니다. git 문서에 따르면 앞이나 중간에 슬래시가 있는 패턴은 그 .gitignore가 있는 폴더를 기준으로만 맞춥니다. 그래서 이 줄은 MyRepo/Library는 잡지만, 한 겹 아래의 MyGame/Library는 지나칩니다. 템플릿 첫 줄 주석에도 이 파일을 유니티 프로젝트 폴더의 루트에 두라고 적혀 있습니다.

같은 구조를 만들어 git으로 확인했습니다. 저장소 맨 위에 둔 Library, Temp, Logs는 무시됐습니다. MyGame 안의 Library와 Temp는 커밋 대상 목록에 그대로 남았습니다.

$ git check-ignore -v Library/x.txt MyGame/Library/x.txt
.gitignore:9:/[Ll]ibrary/	Library/x.txt
  (MyGame/Library/x.txt 줄은 출력되지 않음 = 무시되지 않음)

$ git status --porcelain -uall
?? MyGame/Assets/x.txt
?? MyGame/Library/x.txt
...
?? MyGame/Temp/x.txt

.gitignore는 Assets 폴더와 같은 자리에 있어야 Library를 거릅니다.

고치는 방법은 둘입니다. MyGame 안의 내용물을 저장소 맨 위로 꺼내 .gitignore 옆에 두거나, .gitignore를 MyGame 안으로 옮깁니다. 줄 앞의 /를 **/로 바꿔 어느 깊이든 잡게 하는 방법도 있습니다. 하지만 저장소 하나에 프로젝트 하나라면 위치를 맞추는 편이 단순합니다.

위치가 맞는데도 Library가 계속 변경 목록에 뜬다면 이유가 하나 더 있습니다. .gitignore는 아직 추적하지 않는 파일만 거릅니다. git 문서도 이미 추적 중인 파일은 영향을 받지 않는다고 적습니다. Library를 한 번 커밋한 뒤에 .gitignore를 넣으면, 그 파일은 바뀔 때마다 계속 변경 목록에 뜹니다. 같은 실험에서도 이미 커밋된 Library 파일은 수정됨(M)으로 잡혔고, 새로 생긴 파일만 무시됐습니다. 이 경우는 다음 절의 순서로 추적을 끊어야 합니다.

GitHub 웹의 Add file > Upload files로 폴더를 끌어다 올리는 방법도 피합니다. 브라우저 업로드는 파일당 25MiB, 한 번에 100개 파일까지만 받습니다. 유니티 프로젝트를 올리는 길로는 맞지 않습니다.

4. 이미 올렸다면 되돌리는 순서

어느 경우든 먼저 Unity를 닫고 프로젝트 폴더를 다른 곳에 통째로 복사해 둡니다. 그다음 내 상황이 둘 중 어디인지 봅니다.

push가 거절됐을 때

거절됐다면 Library가 든 커밋은 아직 내 컴퓨터에만 있습니다. 여기서 Library를 지우는 커밋을 하나 더 얹는 것은 소용없습니다. push는 쌓인 커밋을 모두 보내므로 Library를 추가한 커밋도 함께 올라가기 때문입니다. GitHub 문서도 새 커밋만으로는 안 되고, 아직 push하지 않은 기록에서 그 파일을 빼야 한다고 설명합니다. 실험에서도 Library를 지우는 커밋 아래에 Library를 추가한 커밋이 그대로 남아 있었습니다.

1. 커밋 되돌리기: GitHub Desktop 왼쪽 History 탭에서 마지막으로 push에 성공한 커밋을 우클릭하고 Reset to commit을 고릅니다. 처음 올리는 저장소라 push에 성공한 커밋이 없다면 저장소를 만들 때 생긴 Initial commit을 고릅니다. 그 뒤의 커밋들이 풀리고 변경 내용은 작업 폴더에 그대로 남습니다. 되돌릴 커밋이 가장 최근 하나뿐이면 Undo로 같은 일을 합니다.
2. .gitignore 위치 맞추기: .gitignore를 Assets 옆으로 옮기거나 프로젝트 내용물을 .gitignore 옆으로 꺼냅니다.
3. Changes 목록 보기: Library/, Temp/, Logs/, UserSettings/로 시작하는 경로가 하나도 없어야 합니다.
4. 다시 커밋하고 Push origin: 이제 원본 폴더만 올라갑니다.

이미 GitHub에 올라갔을 때

100MiB를 넘는 파일이 없었다면 Library가 그대로 올라가 있을 수 있습니다. 이때는 추적만 끊습니다. GitHub Desktop의 Repository 메뉴에서 명령 프롬프트나 Git Bash를 열고, 유니티 프로젝트 폴더에서 아래를 실행합니다. Git을 찾을 수 없다는 창이 뜨면 Git for Windows를 먼저 설치해야 이 명령이 실행됩니다.

git rm -r --cached --ignore-unmatch Library Temp Logs UserSettings obj
git commit -m "Remove Unity cache folders"
git push

–cached는 저장소의 추적만 끊고 내 컴퓨터의 파일은 남깁니다. –ignore-unmatch는 목록 중 추적하지 않던 폴더가 있어도 멈추지 않게 합니다. 이 옵션 없이 Temp처럼 추적하지 않던 폴더를 함께 적으면 git은 오류를 내고 아무것도 지우지 않습니다. 프로젝트가 한 겹 아래에 있다면 경로 앞에 MyGame/을 붙이고, 3절대로 .gitignore 위치도 맞춥니다. 위치가 그대로면 추적을 끊은 Library가 Changes 목록에 새 파일로 다시 뜹니다.

팀원에게는 미리 알립니다. 이 커밋을 pull하면 팀원 컴퓨터에서 추적되던 Library 파일이 지워집니다. 실험에서도 pull한 쪽의 Library는 사라졌고, 커밋한 쪽의 Library는 남았습니다. Unity를 닫은 상태에서 pull하고, 다음에 열 때 Library를 다시 만드느라 시간이 걸린다고 말해 둡니다.

이 방법은 앞으로의 커밋에서만 Library를 뺍니다. 지난 기록에 남은 용량까지 줄이려면 git filter-repo로 기록을 고쳐 써야 하고, 팀원 전원이 저장소를 다시 받아야 합니다. 저장소 크기가 GitHub 권장선을 넘을 때 아래 GitHub 안내를 읽고 판단합니다.

5. 제대로 걸러졌는지 확인하기

1. GitHub 웹에서 저장소 첫 화면: Assets, Packages, ProjectSettings, .gitignore가 같은 높이에 나란히 보이고 Library가 없으면 맞습니다.
2. 명령으로 한 번 더: 프로젝트 폴더에서 git check-ignore -v Library를 실행해 .gitignore의 줄 번호가 나오면 걸러지고 있는 것입니다. 아무것도 안 나오면 .gitignore 위치와, Library가 아직 추적 중인지(4절)를 다시 봅니다.
3. 팀원 입장에서 받아 보기: 빈 폴더에 저장소를 clone하고 Unity Hub의 Add project from disk로 엽니다. 첫 실행에 Library를 만드느라 오래 걸리는 것은 정상입니다. 패키지 오류 없이 씬이 열리면 끝입니다.

템플릿 원본은 GitHub의 gitignore 저장소에 있습니다. 직접 .gitignore를 만들 때는 이 파일을 내려받아 Assets 옆에 둡니다.

팀원 PC에서 깨지는 쪽이 유니티가 아니라 마야 씬이라면 원인이 다릅니다. 그때는 마야 씬을 다른 PC에서 열 때 텍스처 경로 확인하기부터 보세요.

한 줄 정리

GitHub에는 Assets, Packages, ProjectSettings만 올리고, .gitignore는 Assets 옆에 두면 Library는 내 컴퓨터에 남습니다.