Git Upstream 이란? Upstream과 Origin 차이점과 필요한 이유

soonge2 2025. 3. 4. 15:26

🌿 Git Upstream 이란?

협업을 위해 팀 레포를 fork하고 개인 레포와 로컬 개발환경을 연결해 개발하던 중,

팀 레포에 새로운 브랜치가 생성되었지만 개인 레포에는 자동으로 반영되지 않는 것을 확인했습니다.

이를 해결하기 위해 팀 레포의 브랜치를 개인 레포로 가져오고, 로컬 개발 환경에서도 연결하는 과정을 거치면서 Upstream과 Origin의 개념을 이해하게 되었습니다.

이에 대한 내용을 정리하여 포스팅으로 공유하고자 합니다.

로컬 개발환경에서 원격 저장소와 연결해 개발을 할 때, Origin과 Upstream 이라는 개념이 등장합니다.

둘 다 원격 저장소(remote repository)를 가리키는 이름입니다.

어떤 원격 저장소를 가리키냐에 따라 역할의 차이가 있습니다.

origin: 로컬 개발 환경과 직접 연결된 원격 저장소.
- 내가 clone 한 원격 저장소.
- 내 로컬에서 코드를 push하거나 pull하는 기본적인 대상입니다.
upstream: Fork한 개인 레포가 원본 레포와 동기화할 때 필요한 원격 저장소.
- fork한 경우에만 필요한 개념.
- 원본 레포가 존재하고, 개인 레포가 그 원본에서 fork 되었을 때 사용합니다.

이해하기 쉽도록 그림을 만들어보았습니다.

1. 협업을 위해 팀 레포를 fork해 개인 레포를 생성합니다. (각자 개인 레포에서 개발을 진행한 후 팀 레포에 반영하기 위함입니다.)

2. 개인 레포를 로컬 개발 환경으로 clone하여, 로컬에서 개발을 진행합니다.

3. 개발이 끝난 후, 로컬 개발 환경에서 개인 레포(origin)로 push 합니다.

4. 개인 레포에서 팀 레포(upstream)으로 Pull Request(PR)을 제출합니다.

5. 팀에서 PR을 Merge 하면 원본 레포가 업데이트 됩니다.

upstream은 왜 필요한가요?

Fork한 개인 레포는 원본 레포와 자동으로 동기화되지 않습니다.
즉, 원본 레포가 업데이트되었다고 해서, 개인 레포(origin)가 자동으로 최신 상태가 되는 것이 아닙니다.

따라서 원본 레포의 변경 사항을 수동으로 가져와 동기화해야 합니다.

그래서 원본 레포를 upstream으로 지정하고, git fetch upstream, git pull upstram, git merge 등의 명령어를 사용해 원본 레포와 개인 레포의 동기화를 관리하는 것입니다.

* upstream이 설정되어 있어야, 원본 레포의 변경 사항을 개인 레포와 로컬 개발환경에 반영할 수 있습니다.

1. 원본 레포를 upstream으로 등록

git remote add upstream https://github.com/팀레포.git

아래 명령어를 통해 연결된 것을 확인할 수 있습니다.

git remote -v

2. 원본 레포의 최신 변경 사항 가져오기

git fetch upstream

원본 레포지토리에서 변경 사항을 다운로드합니다.

원본 레포의 변경 사항을 가져와 확인할 수 있으며, 로컬 브랜치는 그대로 유지됩니다.

즉, fetch는 원본 레포의 최신 상태를 로컬 Git 저장소에 다운로드만 할 뿐, 로컬 브랜치에는 영향을 주지 않습니다.

원본 레포의 변경 사항을 로컬 브랜치에 반영하려면, 추가로 merge 또는 pull이 필요합니다.

3. 원본 레포의 특정 브랜치를 로컬에서 업데이트

git pull upstream <병합할 브랜치명>

git fetch upstream은 변경 사항을 다운로드만 했다면,

git pull upstream은 원본 레포(upstream/<브랜치명>)의 변경 사항을 가져와서 내 로컬 브랜치에 병합합니다.

즉, fetch + merge가 자동으로 실행됩니다.