포크한 프로젝트에 원본 저장소 최신 업데이트 안전하게 반영하기

오픈소스 정적 사이트 생성기(SSG)나 템플릿을 포크(Fork)해 나만의 웹사이트를 만드는 경우가 많다. config.yml을 입맛에 맞게 수정하고, 디자인도 손보고, 꽤 공을 들였는데 — 어느 날 원본 프로젝트에 정말 탐나는 새 기능이 추가되었다면?

단순히 덮어쓰면 내 커스텀 설정이 모두 날아가고, 그대로 두자니 새 기능을 누릴 수 없다. 이럴 때 Git의 upstream 설정을 활용하면, 내 수정 사항은 지키면서 원본의 새 기능만 깔끔하게 가져올 수 있다.

1단계. 현재 저장소 상태 확인

작업을 시작하기 전, 로컬 저장소에 연결된 원격 저장소(Remote) 상태를 먼저 확인한다.

git remote -v

정상적인 출력은 아래와 같다.

origin  [email protected]:my-name/my-website.git (fetch)
origin  [email protected]:my-name/my-website.git (push)

현재는 내가 운영 중인 저장소(origin)만 등록된 상태다.

2단계. 원본 저장소(Upstream) 연결

원본 코드가 있는 저장소를 upstream이라는 이름으로 등록한다. 이렇게 해야 원본의 최신 변경 사항을 추적할 수 있다.

# 원본 프로젝트를 upstream으로 추가
git remote add upstream https://github.com/open-source/ssg-template.git

# 제대로 추가되었는지 확인
git remote -v

목록에 origin과 upstream이 모두 표시되면 성공이다.

3단계. 원본 최신 커밋 가져오기 (Fetch)

upstream이 등록됐다면, 원본 저장소의 최신 커밋과 브랜치 정보를 내 컴퓨터로 내려받는다. 이 과정은 실제 코드를 병합하는 것이 아니라 정보만 동기화하는 안전한 단계다.

git fetch upstream

명령 실행 후 upstream/main 브랜치의 최신 내역이 로컬에 다운로드된다.

4단계. 내 브랜치에 병합 (Merge)

이제 가져온 최신 코드를 현재 작업 브랜치(보통 main)에 합친다.

git merge upstream/main

원본이 수정한 파일과 내가 수정한 파일이 겹치지 않는다면 자동으로 병합된다. 그러나 양쪽 모두 config.yml을 수정했다면 충돌(Conflict)이 발생한다. 터미널에 아래와 같은 메시지가 출력된다.

CONFLICT (content): Merge conflict in config.yml
Automatic merge failed; fix conflicts and then commit the result.

5단계. 충돌 해결

당황할 필요 없다. Git이 어느 쪽 내용을 채택해야 할지 모르기 때문에 선택을 우리에게 넘긴 것뿐이다. VS Code 같은 에디터로 충돌 파일을 열면 다음과 같은 구조가 보인다.

<<<<<<< HEAD
# 내가 수정한 내용
title: "나만의 멋진 블로그"
author: "개발자 A"
=======
# 원본 저장소의 최신 내용
title: "기본 SSG 템플릿"
new_awesome_feature: true
>>>>>>> upstream/main

<<<<<<< HEAD ~ ======= : 현재 내 브랜치의 내용
======= ~ >>>>>>> upstream/main : 원본에서 가져온 내용

목표는 내 설정(title: "나만의 멋진 블로그")은 살리고, 원본의 새 기능(new_awesome_feature: true)도 함께 반영하는 것이다. 불필요한 Git 마커(<<<<<<<, =======, >>>>>>>)를 모두 제거하고 아래처럼 정리한 뒤 저장한다.

title: "나만의 멋진 블로그"
author: "개발자 A"
new_awesome_feature: true

6단계. 커밋 후 배포 (Push)

충돌을 모두 해결했다면, 병합 완료를 커밋하고 내 원격 저장소에 푸시한다.

# 해결한 파일 스테이징
git add config.yml

# 병합 완료 커밋
git commit -m "Merge upstream updates and resolve config conflicts"

# 내 저장소에 반영
git push origin main

정리

단계	명령어	설명
상태 확인	`git remote -v`	등록된 원격 저장소 목록 확인
upstream 등록	`git remote add upstream <URL>`	원본 저장소 연결
최신 정보 수신	`git fetch upstream`	원본 커밋 정보 다운로드 (병합 없음)
병합	`git merge upstream/main`	내 브랜치에 원본 변경 사항 반영
충돌 해결	에디터에서 직접 편집	마커 제거 후 원하는 내용으로 정리
배포	`git add` → `git commit` → `git push`	최종 반영

upstream 설정은 한 번만 해두면 이후에는 git fetch upstream → git merge upstream/main 두 단계만으로 원본 업데이트를 안전하게 가져올 수 있다. 내 커스텀 작업물을 지키면서도 오픈소스의 혜택을 꾸준히 누릴 수 있는 실용적인 Git 워크플로다.