Fork로 Git을 처음 쓰는 분을 위한 가이드입니다. GitLab에 있는 Unity·VRChat 프로젝트를 내 컴퓨터에 연결하고, 작업한 내용을 다른 사람과 주고받는 과정을 화면 순서대로 정리했습니다.
처음 연결할 때는 설치와 Clone부터, 이미 프로젝트가 있다면 5장의 작업 흐름부터 보시면 됩니다. 막힌 경우에는 7장에서 오류 문구에 맞는 항목을 찾으세요. 화면은 Windows용 Fork와 이 글의 협업 환경 기준이라 버전이나 서버 설정에 따라 메뉴가 다를 수 있습니다.
Git은 게임의 세이브 파일
0. 커닝페이퍼
급하신 분은 이 세 개만 기억하세요.
Pull, Commit, Push
Pull
→ 다른 사람이 서버에 올린 커밋을 받아 현재 브랜치에 합칩니다. 내 변경이 있다면 먼저 확인하고 Commit하거나 Stash한 뒤 진행합니다. 변경이 겹치면 Git이 Pull을 중단하거나 충돌 해결을 요구할 수 있습니다.
Commit
→ 작업을 완료했을 때, 저장하고 싶을 때 커밋을 하여 내 저장소에 기록합니다
Push
→ 커밋, 저장을 한 데이터를 서버에 반영합니다
1. Git이 뭔가요?
1.1. 파일 이름에 "최종"이 계속 붙는 이유
둘이서 기획서를 고친다고 해보겠습니다. Git이 없으면 대개 이렇게 됩니다.
Git이 없을 때와 있을 때
뭐가 최신인지 모르겠고, 합치다가 한쪽 수정이 날아가기도 합니다. Git은 파일을 하나만 두고 누가, 언제, 뭘 바꿨는지를 전부 기록해주는 프로그램입니다.
가장 쉬운 비유는 게임 세이브입니다. 중간중간 저장해두면 망해도 거기서 다시 시작할 수 있죠. 이 저장을 Git에서는 커밋(Commit)이라고 부릅니다.
1.2. 사용하는 도구 3가지
Git, Fork, GitLab
Git: 파일의 변경 기록과 브랜치를 관리하는 프로그램
Fork: Git을 마우스로 쓰게 해주는 화면. 실제로 만지는 건 이겁니다
GitLab: 모두의 파일이 모이는 서버. 웹사이트라 가입만 하면 됩니다
1.3. 파일이 거치는 4개의 장소
그림은 복잡하지만 4개만 알면 됩니다.
파일이 지나가는 네 곳
이름 | 쉬운 설명 |
|---|
Workspace | 파일 탐색기에서 보이는 온전한 작업 공간 |
Staging | 다음 커밋에 포함하려고 골라둔 변경. 아직 서버에 올라간 상태는 아닙니다 |
Local Repository | 개인 컴퓨터에 각자 존재하는 Git 저장소 |
Remote Repository | 원격 Git 저장소(서버). 여기에 올려야 다른 사람도 내 파일을 받을 수 있습니다 |
Git 전체 구조
택배로 바꿔 말하면 훨씬 쉽습니다.
택배로 보는 Stage, Commit, Push
→ 정리하자면, 우리는 서버에서 최신 작업물을 받고, 내 작업물을 서버에 적용하는 것입니다.
2. 최초 설치
2.1. Git 설치
2.1.1. git-scm.com/install/windows 에서 64-bit Git for Windows Setup을 클릭하여 다운로드 받아주세요
Git 다운로드 페이지
2.1.2. 설치 응용프로그램을 실행하여 우측 하단 Install을 클릭해 설치해주세요
Git 설치 창
💡 싹 다 Next로 넘기시면 됩니다.
2.2. Fork 설치
2.2.1. git-fork.com 에서 Download Fork for Windows를 클릭하여 다운로드 받아주세요
Fork 다운로드 페이지
2.2.2. 처음 실행할 때 이름과 이메일을 물어봅니다. 커밋의 작성자로 남을 정보이며 GitLab 로그인 정보와는 별개입니다. 팀에서 정한 이름과 이메일을 입력하고 Finish를 눌러주세요
Fork 첫 실행
2.2.3. Fork가 정상적으로 설치되었습니다
Fork 시작 화면
💡 다크모드 설정하는 법
다크모드 설정
2.3. GitLab 가입
2.3.1. 팀에서 안내받은 GitLab 주소로 이동합니다. 아래 화면은 회원가입과 관리자 승인을 사용하는 팀 서버의 예시입니다. 회사나 서비스의 가입 방식이 다르면 그 안내를 따르세요
GitLab 로그인 화면
2.3.2. 이름, 닉네임, 이메일, 비밀번호를 모두 채우고 Continue 버튼을 클릭합니다. (본명 안 적고 활동명 채우셔도 됩니다)
2.3.3. 관리자의 승인을 기다립니다. 승인 전에는 로그인이 안 됩니다
💡 계정 정보는 비밀번호 관리 도구에 보관하세요. 서버 설정에 따라 Git 접속에는 비밀번호 대신 토큰이나 SSH 키를 사용할 수 있습니다.
3. Repository 최초 연결
서버에 있는 프로젝트를 내 컴퓨터로 처음 복사해오는 것을 Clone이라고 합니다. 딱 한 번만 하면 됩니다.
3.1. 팀에서 공유한 Repository의 Clone 주소를 복사합니다. 웹사이트의 글 주소가 아니라 Git 저장소의 HTTPS 또는 SSH 주소를 사용합니다
3.2. Fork 창을 열어 좌측 상단 File → Clone 버튼을 찾아 클릭합니다
File 메뉴에서 Clone
3.3. Repository Url에 복사한 주소를 입력합니다
3.4. Parent Folder 우측 폴더 아이콘을 선택하여 컴퓨터에 저장할 위치를 지정합니다
3.5. Clone 버튼을 누릅니다
Clone 창
💡 로그인창이 뜨면
→ 팀에서 안내한 Git 인증 방식으로 로그인합니다. GitLab에서 2단계 인증을 사용한다면 HTTPS Git 접속에 계정 비밀번호 대신 개인 액세스 토큰이 필요합니다. 토큰을 저장소 주소에 넣어 공유하지 마세요.
3.6. 정상적으로 불러와졌다면 이것과 비슷한 상태입니다
Clone 직후 화면
3.7. 왼쪽 Branches에서 팀이 사용하는 로컬 브랜치를 선택합니다. 이 글의 예시는 develop이며 프로젝트에 따라 main 등 다른 이름을 쓸 수 있습니다. 로컬 브랜치가 없다면 Remotes의 origin/develop에서 추적 브랜치를 만듭니다. 커밋 자체를 체크아웃하면 HEAD detached 상태가 될 수 있으므로 브랜치를 선택했는지 확인하세요
💡 Track 창이 뜬다면?
→ 새로운 창의 우측하단 Track 버튼을 클릭합니다
Track 창
3.8. 유니티에 연결
3.8.1. 좌측 상단 Repository → Open in File Explorer를 누르면 파일탐색기에서 유니티 프로젝트 폴더를 확인할 수 있습니다
Repository 메뉴
3.8.2. 유니티 Hub에서 Add project from disk를 통해 저장된 프로젝트를 실행합니다
유니티 허브
3.9. 브챗 프로젝트라면
3.9.1. VRChat Creator Companion에서 Add Existing Project를 통해 저장된 프로젝트를 추가합니다
3.9.2. Manage Project로 들어가면 창이 하나 뜨는데 Resolve 버튼을 누릅니다
3.9.3. Open Project로 프로젝트를 여시면 됩니다
Open Project와 Manage Project
4. Fork 화면 설명
4.1. All Commits 창
All Commits 화면
빨간 구역: 지금까지의 모든 커밋 이력을 확인할 수 있습니다
주황 구역: 빨간 구역에서 선택한 커밋의 세부 기록을 확인할 수 있습니다
파랑 구역: Branch와 Submodules를 확인하는 곳입니다. 현재 작업 브랜치를 확인하되, 익숙하지 않은 브랜치 전환이나 Submodule 조작은 팀에 먼저 확인하세요
노랑 구역: Fetch, Pull, Push 버튼이 모여 있습니다
4.2. Local Changes 창
Local Changes 화면
빨간 구역 (Unstaged): 바뀐 파일을 추적해서 보여줍니다. 파일을 선택하고 우측 상단 Stage 버튼을 누르면 아래 노란 구역으로 이동합니다
보라 구역: 선택한 파일의 변경점을 확인할 수 있습니다
노랑 구역 (Staged): 올리려고 골라둔 파일들입니다. Commit을 하면 여기 있는 파일만 저장됩니다
초록 구역: Commit Subject에 간단한 메모를 남겨 다른 작업자에게 무슨 작업물인지 알려줄 수 있고, Description에 세부 설명을 적을 수 있습니다. 최종적으로 우측 하단 Commit 버튼을 클릭합니다
5. 작업 흐름 (중요)
하루 작업 흐름
5.1. 컴퓨터에 앉기
일단 앉읍시다.
5.2. Fork 켜서 Pull 받기
💡 본격적인 작업에 들어가기 전, 내 파일을 최신 버전으로 만들기 위함입니다.
5.2.1. Fork 창 좌측 상단 Pull 버튼을 클릭합니다
Pull 버튼
5.2.2. Pull 창이 뜨면 좌측 상단 Pull 버튼을 클릭합니다
Pull 창
💡 Stash and reapply local changes 모두 체크해주세요!
변경 사항을 잠시 보관했다가 Pull 후 다시 적용하는 옵션입니다. 다시 적용할 때 충돌할 수도 있으니, 완료 뒤 변경 목록과 Stash 목록을 확인하세요. 새로 만든 파일이 보관 대상에 포함되는지도 확인해야 합니다.
5.3. 열심히 작업하기
💡 중간중간 커밋해도 좋습니다. 많이 할수록 되돌아갈 수 있는 시간대가 늘어나는 것이니 자주자주 해주세요.
5.4. Unstaged 창에서 작업한 파일 Stage하기
5.4.1. Local Changes → Unstaged 창에서 내가 작업한 파일을 선택합니다
5.4.2. 우측 상단 Stage 버튼으로 아래 Staged 창으로 내립니다
Stage 하는 화면
💡 변경 내용을 확인하고 이번 작업에 필요한 파일만 고릅니다. Unity가 바꾼 파일도 필요한 설정 변경일 수 있으니 자동으로 Discard하지 마세요. 새 에셋을 추가했다면 그 에셋의 .meta 파일도 함께 확인합니다.
5.5. Commit하기
5.5.1. Staged에 올릴 파일이 모두 내려간 상태에서 Commit Subject(커밋 제목)와 Description(부가 설명)을 적습니다
5.5.2. Commit 버튼을 누릅니다
Commit 후 기록
5.5.3. All Commits 창에서 내 커밋이 맨 위에 생겼는지 한 번 더 확인합니다
💡 제목은 나중에 봐도 알아볼 수 있게 로비 조명 수정처럼 적어주세요. "수정", "작업"이라고만 써두면 한 달 뒤에 본인도 모릅니다. 작업 파트별로 묶어서 잘게 커밋하면 나중에 Revert로 되돌리기도 편합니다.
5.6. Push 하기
💡 가장 Error가 발생할 확률이 높은 구간입니다. 아래 문제 해결을 참고하여 직접 해결하거나 다른 사람의 도움을 받으세요.
5.6.1. 좌측 상단 Push 버튼을 눌러 서버에 작업물을 업로드합니다
5.6.2. Push 창이 뜨면 아래 체크박스는 모두 해제한 상태에서 Push를 진행합니다
Push 창
5.6.3. 이제 다른 작업자도 Pull을 받아 당신의 작업물을 열람할 수 있습니다
💡 유니티의 경우 .meta 파일까지 같이 올려야 합니다!
6. Discard
Fork를 켰는데 건드린 적도 없는 파일이 Unstaged에 수십 개 떠 있을 때가 있습니다. 당황하지 마세요. 흔한 일이고, 이럴 때 쓰는 게 Discard입니다.
Discard는 되돌리기
6.1. 안 만졌는데 왜 바뀌나요
→ Unity 버전이나 패키지 변화, 임포트, 플러그인 때문에 파일이 바뀔 수 있습니다. 자동으로 바뀌었다는 이유만으로 불필요한 변경이라고 단정하면 안 됩니다. Diff에서 무엇이 달라졌는지 보고 팀에서 제외하기로 한 변경인지 확인한 뒤 처리합니다. .meta, 씬, 프리팹, 프로젝트 설정은 특히 내용을 확인하세요
6.2. Discard 하는 법
6.2.1. Unstaged에서 변경 내용을 확인하고, 버려도 된다고 확인한 파일만 선택합니다. 모르는 파일은 선택하지 않습니다
6.2.2. 우클릭 → Discard changes를 누릅니다 (단축키 Delete)
Discard changes 메뉴
6.2.3. 추적 중인 파일의 변경을 버리면 현재 체크아웃한 커밋 기준으로 돌아갑니다. 서버의 최신 파일을 새로 받는 동작은 아닙니다. 새 파일을 삭제하는 동작인지도 확인한 뒤 진행하세요
6.3. 누르기 전에 한 번만 생각해주세요
Discard 전 질문
상황 | Discard |
|---|
직접 편집하지 않았지만 Unity가 바꾼 파일 | Diff와 팀의 처리 기준을 먼저 확인합니다 |
Commit·Push 뒤 남은 변경 | 이름만 보고 버리지 말고 내용을 확인합니다 |
내가 일부러 고친 파일 | 하면 안 됩니다 |
아직 저장 안 한 작업 중인 파일 | 하면 안 됩니다 |
뭔지 모르겠는 파일 | 그대로 두고 물어보세요 |
💡 Discard는 되돌릴 수 없습니다. 휴지통에 들어가는 게 아니라 고친 내용이 그냥 증발합니다.
6.4. 헷갈리면 Stash
버려도 되는지 모르겠으면 먼저 Commit하거나 Stash로 보관합니다. Fork의 파일별 Stash 메뉴를 쓸 때도 어떤 파일이 포함되는지 확인하세요. 새로 만든 파일은 옵션에 따라 빠질 수 있고, 다시 적용할 때 충돌할 수도 있습니다. 보관 결과를 확인한 뒤 다음 작업을 합니다.
6.5. 자주 묻는 것
Q. Discard했는데 유니티를 켜니 또 떠요.
→ Unity나 패키지가 같은 변경을 다시 만들 수 있습니다. 반복해서 Discard하기보다 어떤 파일인지 확인하고, 팀에서 공유해야 할 설정인지 또는 생성 파일 관리가 필요한지 먼저 확인하세요.
Q. 내 작업을 Discard해버렸어요.
→ 저장 안 한 내용은 Git에 기록이 없어서 Git으로는 못 살립니다. 유니티가 아직 열려 있다면 Ctrl+Z가 먹히는지 먼저 확인하세요. 그래서 자주 커밋하라고 하는 겁니다. 커밋해둔 건 어떻게든 살립니다.
Q. Discard랑 Revert는 뭐가 달라요?
| Discard | Revert |
|---|
대상 | 아직 저장 안 한 변경 | 이미 저장한 커밋 |
동작 | 고친 내용을 버립니다 | 그 커밋을 취소하는 새 커밋을 만듭니다 |
복구 | 불가능 | 기록이 남아서 가능 |
7. 여러 Error 해결 방법
에러가 떠도 대부분은 아래에 있는 것 중 하나입니다. 뭐가 떴든 시작은 똑같습니다.
막혔을 때 순서
💡 먼저 이 세 가지를 지켜주세요.
에러 문구를 그대로 캡처합니다
내 작업이 커밋되어 있는지 확인합니다
Discard나 Reset은 누르지 않습니다. 증거만 지우는 꼴이 될 수 있습니다
7.1. Push가 거절됩니다 (rejected, non-fast-forward)
Push가 안 될 때
→ 내가 일하는 동안 다른 사람이 먼저 올려서 서버가 더 최신이 된 상태입니다 → Pull을 받고 다시 Push하면 대부분 해결됩니다 → Pull 중에 충돌이 났다면 7.3으로 갑니다
💡 Push 창에 Force push가 있는데 켜면 안 됩니다. 거절을 무시하고 덮어써서 남의 작업을 날릴 수 있습니다.
7.2. Pull이 안 됩니다 (local changes would be overwritten)
저장 안 한 내 변경이 있는데 받을 내용이 같은 파일을 바꾸려 해서 멈춘 겁니다.
7.2.1. Pull 창에서 Stash and reapply local changes를 체크하고 다시 합니다
7.2.2. 안 되면 내가 고친 파일을 먼저 Commit하고 Pull합니다
7.2.3. 직접 편집하지 않은 파일도 변경 내용을 확인합니다. 버려도 되는 변경인지 확실하지 않다면 Discard하지 말고 보관하거나 팀에 확인합니다
7.3. 충돌이 났습니다 (Conflict)
충돌이란
나와 다른 사람이 같은 파일의 같은 부분을 다르게 고치면 Git이 멈춥니다. 고장이 아니라 어느 쪽이 맞는지 사람이 정해달라는 신호입니다.
7.3.1. 경고 표시가 붙은 파일을 찾아 우클릭합니다
7.3.2. 내 것으로 할지 서버 것으로 할지 고르는 메뉴가 있습니다. 이름은 Fork 버전에 따라 조금 다릅니다
7.3.3. 충돌을 해결한 파일을 열어 필요한 내용이 남아 있는지 확인합니다. Stage한 뒤 Fork가 안내하는 Commit 또는 Continue로 진행하고, 프로젝트도 열어 확인합니다
유니티 씬이나 프리팹이 충돌했는데 어느 쪽이 맞는지 모르겠다면 혼자 고르지 마시고 상대와 상의하세요. 반쯤 합쳐진 씬은 아예 안 열릴 수도 있습니다. 겁나면 Abort로 시도 이전 상태로 돌아갈 수 있습니다.
7.4. 로그인이 안 됩니다 (Authentication failed, 401, 403)
증상 | 확인할 것 |
|---|
가입 직후부터 실패 | 관리자 승인이 아직일 수 있습니다 |
Git 인증이 실패합니다 | 저장소 권한과 HTTPS 토큰·SSH 등 팀의 인증 방식을 확인하세요. Fork의 작성자 이름·이메일과 GitLab 로그인은 별개입니다 |
비밀번호를 바꾼 뒤부터 | 윈도우 자격 증명 관리자에서 GitLab 항목을 지우면 새로 물어봅니다 |
맞는 것 같은데 안 됩니다 | 웹 브라우저로 GitLab에 직접 로그인해보세요 |
7.5. Clone이 안 됩니다
→ 저장소 주소 앞뒤에 공백이 붙어 있지 않은지 확인합니다 → 저장할 폴더는 비어 있어야 합니다. 새 폴더를 만들어서 고르세요 → 경로가 너무 길면 문제가 될 수 있습니다. 드라이브 바로 아래처럼 짧은 곳이 좋습니다 → 인터넷 연결과 GitLab 사이트 접속을 확인합니다
7.6. 커밋을 잘못했습니다
→ 아직 Push 전이고 방금 한 커밋이면, 커밋 창에서 Amend를 켜고 파일을 더하거나 메모를 고쳐서 다시 저장합니다 → 이미 Push했다면, 그 커밋을 우클릭해서 Revert commit을 합니다. 되돌리는 새 커밋이 생기니 다시 Push하면 됩니다
💡 이미 서버에 올라간 커밋을 Reset으로 지우거나 Force push로 덮어쓰지 마세요. 다른 사람 기록까지 꼬입니다.
7.7. Push했는데 남이 못 봅니다
대개 Commit만 하고 Push를 안 한 경우입니다. Push 버튼 옆에 숫자나 위쪽 화살표가 남아 있으면 아직 서버로 안 간 커밋이 있다는 뜻입니다. 그래도 안 보이면 상대가 Pull을 했는지, 같은 브랜치(develop)를 보고 있는지 확인하세요.
7.8. Unity의 분홍색 머티리얼·누락된 오브젝트
분홍색 머티리얼은 셰이더 오류나 렌더 파이프라인 불일치부터 확인합니다. 오브젝트나 에셋 참조가 빠졌다면 원본 파일과 .meta가 함께 공유됐는지도 확인하세요. 두 증상을 같은 원인으로 단정하지 않습니다. Pull 후 임포트 중이라면 완료를 기다린 뒤 Console의 오류를 확인합니다.
7.9. HEAD detached라고 뜹니다
브랜치 대신 특정 커밋을 체크아웃한 상태입니다. 아직 작업하지 않았다면 왼쪽 Branches에서 팀의 작업 브랜치로 돌아갑니다. 이미 수정했거나 커밋했다면 바로 이동하기 전에 현재 위치에서 새 브랜치를 만들어 기록을 보존하세요. 브랜치 이름은 팀과 정하면 됩니다.
7.10. index.lock 에러
이전 Git 작업이 비정상으로 끝나서 잠금 파일이 남은 경우입니다. Fork를 완전히 종료했다가 다시 켜보세요. 같은 프로젝트를 여는 다른 Git 프로그램이 없는지도 확인하시고, 그래도 안 되면 파일을 직접 지우지 말고 캡처와 같이 물어봐주세요.
7.11. 파일이 너무 커서 Push가 안 됩니다
too large, 413, timeout 같은 문구가 보이면 용량 문제입니다. 어떤 파일인지 캡처해서 관리자에게 알려주세요. 큰 파일은 따로 관리해야 하는 경우가 많습니다.
7.12. 도움을 요청할 때
디스코드에 아래 세 가지를 같이 남기면 대부분 바로 답이 달립니다.
에러 화면 캡처 (문구가 읽히게)
뭘 하다가 그랬는지 (Pull 중인지 Push 중인지)
내 작업이 커밋되어 있는지
8. Git 협업 Tip
같이 일할 때 지킬 5가지
작업 시작 전 Pull 땡기고 시작하자
💡 이전까지의 모든 작업 사항을 업데이트하고 제일 최신 버전에서 시작해야 충돌 참사를 피할 수 있습니다!
Unstaged의 변경 내용을 알고 작업하자
💡 Unstaged는 아직 커밋에 포함하지 않은 변경입니다. 필요한 변경은 Stage·Commit하고, 이유를 모르는 변경은 보관한 뒤 확인하세요. 목록을 비우려고 일괄 Discard하지 않습니다.
그때그때 Commit 하자
💡 Commit을 할수록 되돌아갈 수 있는 세이브포인트가 늘어납니다. 제에발 커밋하세요. 어떻게든 살려드립니다..
같은 Scene은 동시에 작업하지 말자
💡 두 명이 같은 Scene의 완벽히 다른 Object를 만지면 Git에서 Merge를 시켜줄 수도 있지만, 어지간하면 그런 일은 없으니 같은 Scene은 동시에 만지지 맙시다. 디스코드에 "이 씬 만져요" 한마디만 남겨도 충분합니다.
작업 단위를 확인하고 자주 Push하자
💡 확인이 끝난 작은 작업 단위로 Commit·Push하면 서로의 변경을 일찍 확인할 수 있습니다. 충돌에서는 서버 쪽이나 내 쪽을 무조건 살리는 대신, 필요한 내용을 함께 확인해 결정합니다.
9. 용어 사전
용어 사전
자주 쓰는 Git 용어를 글로 정리하면
- Clone
- 서버의 저장소를 내 컴퓨터에 처음 복사합니다.
- Fetch
- 서버의 새 기록을 받아옵니다. 현재 작업 브랜치에 바로 합치지는 않습니다.
- Pull
- 새 기록을 받아 현재 브랜치에 통합합니다.
- Stage
- 다음 커밋에 넣을 변경을 고릅니다.
- Commit
- 선택한 변경을 내 저장소의 기록으로 남깁니다.
- Push
- 로컬 커밋을 서버에 보냅니다.
- Stash
- 진행 중인 변경을 잠시 보관합니다.
- Discard
- 선택한 작업 변경을 버립니다. 먼저 보관이 필요한지 확인해야 합니다.
다음으로 볼 글
프로젝트 전체가 아니라 Unity 패키지 하나를 Git 주소로 추가하려면 Package Manager의 Git 패키지 설치 방법을 참고하세요. 커스텀 패키지를 실제 프로젝트에 붙인 사례는 Unity URP 커스텀 DOF 개발기에 정리했습니다.
Git의 동작 기준은 Pull, Stash, 브랜치 전환 문서에서 확인할 수 있습니다. HTTPS 인증은 GitLab 토큰 안내를 참고하세요.