🚀 Xcode 프로젝트와 GitHub 원격 저장소 연결 및 병합 오류 해결 완전 가이드

Xcode에서 앱을 개발하다 보면,
프로젝트를 GitHub에 올리거나 업데이트하는 과정에서
“fatal: refusing to merge unrelated histories”
또는
“fatal: 'origin' does not appear to be a git repository”
같은 에러를 겪는 경우가 자주 있습니다.

 

이번 글에서는 실제 사례를 바탕으로,
이 문제들이 왜 발생하는지,
그리고 어떤 명령어로 해결할 수 있는지를
단계별로 정리해봤습니다.

---

 

🧩 1. 문제의 시작 — GitHub에서 README 수정 후 Xcode에서 Pull 시도

처음 상황은 다음과 같았습니다 👇

 

1. GitHub 원격 저장소에는 이미 README.md 파일이 존재했고, GitHub 웹사이트에서 해당 파일을 수정함.

2. 반면, 로컬(Xcode 프로젝트)에는 이 수정된 내용이 아직 반영되지 않은 상태였음.

3. 그래서 SourceTree 또는 Terminal에서 pull을 눌러 원격 변경사항을 내려받으려 했음.

 

그런데 다음과 같은 에러가 발생했습니다 👇

fatal: refusing to merge unrelated histories

---

🧠 2. 원인 분석 — 서로 다른 Git 이력(history) 때문

이 에러는 로컬 저장소와 원격 저장소의 Git 이력이 완전히 다를 때 발생합니다.

 

즉,

로컬 프로젝트는 Xcode에서 git init을 새로 실행해서 Git을 처음 시작했고,

GitHub 원격 저장소는 이미 README.md, LICENSE 등의 파일을 포함하고 있었기 때문에

 

👉 서로 “다른 히스토리”로 인식된 겁니다.

 

Git은 기본적으로 “관계 없는 두 프로젝트를 병합하는 것”을 거부하기 때문에
이런 오류 메시지를 띄웁니다.

---

⚠️ 3. 추가 오류 — 'origin' does not appear to be a git repository

문제를 해결하려고 git pull origin main --allow-unrelated-histories 명령어를 실행했는데
이번에는 아래와 같은 새로운 에러가 나왔습니다 👇

fatal: 'origin' does not appear to be a git repository
fatal: Could not read from remote repository.

 

이건 Git이 원격 저장소(origin)의 주소를 모르기 때문이에요.
즉, 로컬 프로젝트에 원격 주소가 아직 연결되지 않은 상태였습니다.

---

🔧 4. 해결 방법 — GitHub 저장소와 로컬 프로젝트 연결하기

먼저, 로컬 저장소가 GitHub 저장소와 연결되어 있는지 확인합니다.

git remote -v

 

만약 아무것도 표시되지 않거나
origin이 없으면 아래 명령어로 원격 저장소를 연결해야 합니다 👇

git remote add origin https://github.com/89Explorer/LemonLog.git

 

다시 한 번 확인해볼까요?

git remote -v

 

정상이라면 이렇게 나와야 합니다 ✅

origin  https://github.com/89Explorer/LemonLog.git (fetch)
origin  https://github.com/89Explorer/LemonLog.git (push)

---

🧱 5. 병합 시도 — unrelated histories 에러 해결

이제 두 저장소가 연결되었으니,
이제 본격적으로 “이력 병합”을 진행할 수 있습니다.

git pull origin main --allow-unrelated-histories

 

이 명령어는
“서로 다른 두 Git 프로젝트라도 강제로 병합해라”
라는 의미입니다.

---

🧩 6. 새로운 에러 — “Need to specify how to reconcile divergent branches”

병합 과정에서 Git이 또 멈추며 아래 메시지를 띄울 수 있습니다.

fatal: Need to specify how to reconcile divergent branches.

 

이는 Git이 “어떤 방식으로 두 브랜치를 병합해야 하는지”를 모르는 경우 발생합니다.

즉, merge 방식을 명시적으로 알려줘야 합니다.

---

🔨 7. 병합 방식 지정 및 최종 해결

아래 명령어를 입력합니다 👇

git pull origin main --allow-unrelated-histories --rebase=false

 

🔍 의미

--allow-unrelated-histories : 서로 다른 프로젝트 이력을 강제로 병합

--rebase=false : rebase 대신 merge 방식으로 병합

---

✍️ 8. vi 편집기 창이 열리는 경우 (병합 메시지 작성)

명령어 실행 후 아래와 같은 화면이 뜰 수 있습니다 👇

Merge branch 'main' of https://github.com/89Explorer/LemonLog
# Please enter a commit message to explain why this merge is necessary

 

이는 Git이 자동으로 병합 커밋 메시지를 작성하라고 띄운 화면이에요.

아무것도 수정하지 않고 저장 후 종료하면 됩니다.

 

🔹 종료 방법:

esc 키 누르기

:wq 입력

Enter 키

 

이제 병합이 완료됩니다 ✅

---

🚢 9. 병합 완료 후 GitHub에 업로드 (Push)

이제 로컬에서 GitHub로 푸시할 차례입니다.

git push origin main

 

이제 로컬 프로젝트와 GitHub 저장소가 완전히 동기화되었습니다 🎉