깃(Git)을 사용해 오픈소스 프로젝트에 기여하거나 협업을 진행할 때는 원본 저장소를 복제하는 포크(Fork) 기능을 자주 사용한다. 포크를 통해 생성된 개인 원격 저장소는 작업이 진행되는 동안 원본 저장소에 새롭게 추가된 커밋 이력과 차이가 발생하게 된다. 이때 원본 저장소를 가리키는 업스트림(upstream) 원격 저장소를 로컬 환경에 등록하면 최신 변경사항을 주기적으로 동기화할 수 있다. 이 글에서는 업스트림 원격 저장소를 로컬 저장소에 추가하고 최신 이력을 내려받아 병합한 뒤 필요에 따라 연결을 해제하는 전체 과정을 다룬다.
upstream이란? 다른 개발자가 생성한 원격 저장소와 내 저장소를 동기화
업스트림(upstream)은 깃에서 포크의 대상이 된 원래의 원본 원격 저장소를 가리키는 관례적인 명칭이다. 사용자가 포크하여 생성한 본인의 원격 저장소는 기본적으로 오리진(origin)이라는 이름으로 설정되며, 원본 프로젝트 저장소는 업스트림(upstream)으로 지정하여 구분한다. 강물이 흐르는 방향에 빗대어 보면 원본 저장소는 강의 상류(upstream)에 해당하고, 복제된 개인 저장소는 하류(downstream)에 해당한다. 상류에서 새롭게 흘러내려오는 최신 코드 이력을 하류에 위치한 로컬 작업 공간으로 지속해서 가져와 합치는 작업이 동기화이다.
로컬 저장소에 upstream 원격 저장소를 추가
로컬 저장소의 원격 연결 목록에 원본 저장소의 주소를 `upstream`이라는 별칭으로 등록하는 명령어다. `git remote add` 뒤에 사용할 원격 저장소 별칭과 대상 저장소의 주소를 지정한다. 원격 저장소를 등록해 두면 긴 전체 URL을 반복해서 입력할 필요 없이 별칭을 통해 원본 저장소와 통신할 수 있다.
git remote add upstream [원격 저장소 URL]
`[원격 저장소 URL]` 부분에는 대괄호를 제외하고 원본 저장소의 실제 주소(HTTPS 또는 SSH 형식)를 입력해야 한다. 이미 동일한 이름의 원격 저장소가 등록되어 있다면 중복 오류가 발생하므로, 사전에 `git remote -v` 명령어를 실행하여 현재 연결된 원격 저장소 목록을 확인하는 것이 권장된다.
upstream 원격 저장소의 변경사항을 로컬 저장소로 가져오기
등록된 업스트림(upstream) 원격 저장소의 최신 브랜치 정보와 커밋 이력을 로컬 저장소로 내려받는 명령어다. 페치(fetch) 명령은 원격 저장소의 변경사항을 로컬의 원격 추적 브랜치로만 가져오며, 현재 작업 중인 로컬 브랜치의 코드에는 직접적인 영향을 주지 않는다. 따라서 작업 중인 코드가 의도치 않게 변경될 위험 없이 최신 이력을 안전하게 확인할 수 있다.
git fetch upstream
`git fetch upstream`을 실행한 직후에는 로컬 작업 디렉터리의 파일이 즉시 갱신되지 않는다. 이력 정보는 `upstream/main`과 같은 원격 추적 브랜치에 저장된 상태이므로, 로컬 브랜치에 반영하기 위해서는 별도의 병합(merge) 과정을 거쳐야 한다.
가져온 upstream 변경사항을 로컬 브랜치에 병합
페치(fetch)를 통해 내려받은 업스트림 원격 저장소의 특정 브랜치 이력을 현재 작업 중인 로컬 브랜치에 병합(merge)하는 명령어다. 원본 저장소의 기본 브랜치 이름이 `main`이라면 `git merge upstream/main`을 실행하여 로컬 브랜치를 원본 저장소의 최신 상태로 갱신한다.
git merge upstream/[브랜치 이름]
병합을 실행하기 전에는 반드시 동기화 대상이 되는 로컬 브랜치로 체크아웃(checkout)되어 있는지 확인해야 한다. 원본 저장소의 변경사항과 로컬에서 수정한 내용이 동일한 파일의 같은 위치에서 겹칠 경우 충돌(conflict)이 발생할 수 있다. 충돌이 발생하면 충돌 표식을 수정한 뒤 변경사항을 커밋해야 병합이 완료된다.
upstream 원격 저장소 설정 제거
로컬 저장소 설정에서 `upstream`으로 등록되었던 원격 저장소 연결 정보를 삭제하는 명령어다. 프로젝트 기여가 끝나 더 이상 원본 저장소의 이력을 추적할 필요가 없거나 원격 저장소 주소가 변경되었을 때 연결 설정을 정리하기 위해 사용한다.
git remote remove upstream
이 명령어는 로컬 Git 환경설정에서 원격 연결 별칭만 삭제할 뿐, 이미 로컬 브랜치에 병합된 커밋 이력이나 실제 원격 저장소 자체에는 영향을 미치지 않는다. 명령 실행 후 `git remote -v` 명령어를 통해 목록에서 정상적으로 제외되었는지 확인할 수 있다.