git: fatal: refusing to merge unrelated histories

안녕하세요, BlueByte입니다. pull이 방금 "refusing to merge unrelated histories"로 멈췄다면, 깨진 게 아닙니다 — git이 무관한 두 프로젝트를 실수로 엮지 않게 막아주는 것입니다. 오늘은 두 쪽이 정말 같은 프로젝트인지 확인한 뒤, 그것을 허용하는 플래그 하나를 켜는 순서로 가보겠습니다.

이 메시지가 뜻하는 것

pull이나 merge가 이렇게 멈춥니다:

fatal: refusing to merge unrelated histories

두 쪽이 공통 조상을 공유하지 않습니다. 무관한 히스토리를 합치는 건 대개 실수라 git이 거부합니다 — 하지만 정말 원하는 경우엔 플래그 하나로 허용됩니다. 깨진 게 아니라 안전장치입니다.

두 히스토리에 공통 커밋이 없는 이유

Git 2.9부터 git merge와 git pull은 공통 커밋이 없는 두 히스토리 결합을 거부합니다. 알아볼 수 있는 몇 상황:

• 로컬 폴더에 git init 후 커밋했는데, 이미 자체 초기 커밋이 있는 리모트를 연결. 두 초기 커밋이 무관.
• 별개 저장소 둘을 하나로 병합.
• --orphan으로 브랜치를 강제 생성한 뒤 다시 병합하려 함.
• 저장소를 처음부터 다시 만들고(.git 삭제 후 git init) 옛 리모트를 pull — 이제 무관해 보임.

양쪽이 같은 프로젝트인지 먼저 확인

병합을 눈감고 허용하지 말고, 양쪽 로그를 보고 합치려는 그 프로젝트가 맞는지 확인하세요:

git log --oneline -5 HEAD
git log --oneline -5 origin/main

두 로그가 명백히 같은 프로젝트가 두 번 시작된 거면 병합해도 안전합니다. origin/main이 완전히 다른 프로젝트면 멈추세요 — 엉뚱한 리모트를 병합하려는 것입니다. git merge-base HEAD origin/main으로 공유 커밋이 정말 없는지도 확인할 수 있습니다(무관하면 아무것도 안 찍힘).

확신이 서면 병합을 허용하기

히스토리가 합쳐질 게 맞다고 확인했으면 명시적으로 허용:

git pull origin main --allow-unrelated-histories

이미 fetch했다면:

git merge origin/main --allow-unrelated-histories

충돌을 평소처럼 해결하고 커밋합니다. 두 히스토리가 병합 커밋 하나에서 이어집니다.

실제 사례: 리모트에 있던 README

git init으로 로컬 프로젝트를 만들고 세 커밋을 한 뒤, 호스트에 빈 저장소를 만들었는데 — 생성 시 README가 추가되며 자체 초기 커밋이 생겼습니다. git pull origin main이 "refusing to merge unrelated histories"로 실패합니다. 양쪽 git log가 같은 프로젝트가 두 번 시작된 것을 보여주고 git merge-base가 아무것도 안 찍어 공유 커밋 없음을 확인합니다. git pull origin main --allow-unrelated-histories를 실행하고 사소한 README 충돌을 해결한 뒤 커밋합니다. 그래프가 이제 세 커밋을 호스트의 README 커밋에 잇는 병합 커밋 하나를 보여줍니다.

히스토리가 실제로 이어졌는지 확인

두 줄기가 만났고 파일이 다 있는지 확인:

git log --oneline --graph -8

두 히스토리가 만나는 병합 커밋 하나가 보이고 그 아래로 양쪽 커밋이 모두 도달 가능해야 합니다.

다시 겪지 않으려면

로컬 폴더가 기존 리모트를 추적하게 하려면 git init + 리모트 추가 대신 리모트를 먼저 clone하고 파일을 복사해 넣으세요 — 그러면 처음부터 하나의 공유 히스토리라 이 문제가 안 생깁니다. 기존 로컬 히스토리를 push할 거면 리모트 저장소를 비어 있게(README 없이) 만드세요.

병합 충돌과의 구분

이건 병합 충돌이 아닙니다 — 충돌은 병합이 시작된 뒤 특정 라인에서 생깁니다. refusing to merge unrelated histories는 diff할 공통 베이스가 없어 병합이 아예 시작조차 안 되게 막는 것입니다. 허용하고 나면 평범한 충돌 해결이 그 뒤를 이어받습니다.