fatal: refusing to merge unrelated histories 5분 해결 (복붙 명령어)

일단 진정하세요 — 코드는 안 날아갔습니다

방금 터미널에서 fatal: refusing to merge unrelated histories를 만나 검색창에 그대로 붙여넣고 들어오셨죠? 좋은 소식부터 말씀드립니다. 이건 데이터가 사라지는 에러가 아닙니다. 오히려 Git이 "이대로 합치면 위험하니 잠깐 멈추겠다"고 안전장치를 작동시킨 것뿐입니다. 로컬 코드도, 원격 코드도 그대로 살아 있습니다.

대부분 아래 세 시나리오 중 하나입니다.

• ① GitHub에서 README/LICENSE 체크하고 repo를 만든 뒤, 로컬에서 따로 작업하던 코드를 처음 git pull 하려는 경우 (가장 흔함)
• ② 두 프로젝트를 합치려는데 양쪽 모두 진짜 커밋 히스토리가 있는 경우
• ③ 실수로 .git 폴더를 지우고 git init을 다시 해서 히스토리가 끊긴 경우

"내 상황이 여기 있다" 싶으면, 아래로 내려가 해당 분기의 명령어를 복붙하시면 됩니다.

왜 막히는가: 공통 조상 커밋이 없기 때문

핵심 정의 한 줄입니다. Git은 두 브랜치가 공통 조상 커밋(merge base)을 공유하지 않으면 "관련 없는 히스토리"로 판단하고 병합을 거부합니다.

GitHub에서 README를 추가하며 repo를 만들면, 원격에는 이미 첫 커밋 B1이 생깁니다. 그런데 내 로컬은 git init 후 독립적으로 A1 → A2를 쌓아왔죠. 두 갈래는 시작점이 완전히 다릅니다.

로컬 (origin과 무관한 첫 커밋에서 시작)
    A1 ── A2   (main)

원격 (GitHub가 만든 README 커밋에서 시작)
    B1         (origin/main)

       ↑ 둘을 잇는 공통 조상(merge base)이 없음 → Git이 병합 거부

일반적인 병합은 "공통 조상에서 갈라진 두 갈래"를 다시 모으는 작업입니다. 그런데 위처럼 출발점 자체가 다르면 Git은 "이게 정말 같은 프로젝트가 맞나? 혹시 엉뚱한 repo끼리 합치는 건 아닌가?" 의심하며 멈춥니다. 그래서 --allow-unrelated-histories로 "맞으니까 강제로 합쳐줘"라고 명시해줘야 합니다.

상황별 해결 분기 (복붙)

① 원격이 README/LICENSE만 있는 사실상 빈 repo

가장 흔한 케이스입니다. 로컬 코드를 살리면서 원격의 README까지 가져오려면 한 줄이면 됩니다.

git pull origin main --allow-unrelated-histories
# 원격 main을 가져와 로컬과 강제 병합 → 이후 git push

⚠️ 경고 --allow-unrelated-histories는 서로 무관한 두 히스토리를 강제로 하나로 묶는 옵션입니다. URL을 잘못 적어 엉뚱한 repo에 실행하면 남의 프로젝트 파일이 통째로 내 repo에 섞여 들어옵니다. 실행 전 git remote -v로 origin URL이 맞는지 꼭 확인하세요.

만약 원격 README가 필요 없고 로컬 내용으로 통째로 덮어써도 된다면, 병합 없이 강제 푸시가 더 깔끔합니다(원격 커밋이 사라지니 주의).

git push -u origin main --force   # 원격 README 커밋을 버리고 로컬로 덮어씀

② 양쪽에 진짜 작업 커밋이 다 있는 경우

두 갈래 모두 의미 있는 커밋이라면, 아래 "안전한 병합 실전" 절차대로 fetch 후 명시적으로 병합하는 걸 권합니다. 한 줄 버전(git pull ... --allow-unrelated-histories)도 동작하지만, 두 프로젝트 파일이 한 번에 섞이므로 단계를 나눠 확인하는 편이 안전합니다.

③ .git을 잘못 재초기화해 히스토리가 끊긴 경우

원래 히스토리를 복구하고 싶다면 git reflog나 백업에서 되살리는 게 정석입니다. 단순히 현재 상태만 원격에 올리면 된다면 ②와 동일하게 --allow-unrelated-histories로 묶으면 됩니다.

안전한 병합 실전: 단계별 절차

복붙 한 줄이 무서운 분을 위한 정공법입니다. 각 단계가 무엇을 하는지 주석으로 달았습니다.

git remote add origin https://github.com/계정/repo.git  # 원격 저장소 연결
git fetch origin                                        # 원격 내용 받아오기(병합 X, 확인만)
git merge origin/main --allow-unrelated-histories       # 무관한 히스토리 명시 후 병합
# (충돌이 나면 아래 '충돌 처리' 참고)
git push -u origin main                                 # 병합 결과를 원격에 올리고 추적 설정

fetch → merge로 나누면, 병합 전에 git log origin/main으로 원격에 뭐가 들었는지 눈으로 확인할 수 있어 사고를 줄일 수 있습니다.

💡 실무 팁(경험담): 저는 신규 repo를 합칠 때 항상 git fetch부터 합니다. 예전에 git pull 한 줄로 처리하다가, README 충돌 + 남의 .gitignore가 섞여 들어와 30분을 날린 적이 있거든요. "복붙은 빠르지만, fetch는 안전하다"가 제 결론입니다.

충돌 처리 흐름

양쪽에 README.md가 다 있으면 병합 시 십중팔구 이런 메시지가 뜹니다.

CONFLICT (add/add): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.

당황하지 말고 순서대로 처리하세요.

git status            # 충돌난 파일 목록 확인 (both modified 표시)
# 편집기로 README.md 열어 <<<<<<< ======= >>>>>>> 마커 정리
git add README.md     # 해결 완료 표시
git commit            # 병합 커밋 마무리

<<<<<<<(내 변경)과 >>>>>>>(원격 변경) 사이에서 원하는 내용만 남기고 마커를 지우면 됩니다. 더 복잡한 충돌이나 rebase 중 충돌이 헷갈린다면, 별도 글 'git rebase 충돌 해결' 편을 함께 참고하세요(블로그 내부 링크).

잘못 합쳤을 때 되돌리기

엉뚱하게 섞였다면 즉시 되돌릴 수 있습니다.

# 방법 1: 병합 직후라면 한 줄로 복구
git reset --hard ORIG_HEAD

ORIG_HEAD는 Git이 병합·리셋 등 위험한 작업 직전 위치를 자동으로 기억해두는 포인터입니다. 그래서 병합 바로 다음이라면 이 한 줄로 깔끔하게 원상복구됩니다.

# 방법 2: 이미 다른 작업을 했다면 reflog로 직전 커밋 찾기
git reflog                      # 모든 HEAD 이동 기록 확인
git reset --hard <병합전_해시>   # 원하는 시점으로 복귀

reflog는 일반 git log에 안 보이는 "내가 거쳐온 모든 위치"까지 기록하는 안전망이라, 잘못 리셋·병합한 커밋도 해시만 알면 되살릴 수 있습니다.

다음엔 이 에러를 아예 안 보는 체크리스트

• 신규 repo를 GitHub에서 만들 때 README/LICENSE/.gitignore를 체크하지 않고 완전히 빈 repo로 생성
• 그 빈 repo에 로컬 코드를 git remote add → git push -u origin main으로 처음 올리기 (이러면 공통 조상이 자연스럽게 생겨 에러 자체가 안 남)
• README가 꼭 필요하면 로컬에서 만들어 첫 커밋에 포함시키기

GitHub가 repo 생성 시 README 자동 추가를 기본으로 권하면서 입문자에게 이 에러가 폭증하고 있습니다. "처음엔 빈 repo, 파일은 로컬에서"를 기억하면 대부분 예방됩니다.

자주 묻는 질문 (FAQ)

Q1. 옵션을 줬는데도 또 거부당해요. A. 십중팔구 브랜치명 오타입니다. 원격 기본 브랜치가 main인지 master인지 git branch -r로 확인하세요. 기본 브랜치명이 master→main으로 바뀌면서 옛날 예시(master)를 그대로 쓰면 엉뚱한 브랜치를 가리켜 실패합니다.

Q2. main이 아니라 master라고 나와요. A. 명령어의 main을 전부 master로 바꾸면 됩니다. 또는 git branch -M main으로 로컬 브랜치명을 통일한 뒤 진행하세요.

Q3. 브랜치명을 빼먹으니 다른 에러가 나요. A. git pull origin --allow-unrelated-histories처럼 브랜치를 생략하면 "어느 브랜치를 가져올지 모른다"는 별개의 에러가 납니다. 반드시 git pull origin main ...처럼 브랜치명을 명시하세요. 이건 unrelated histories 문제와는 다른 원인입니다.