fatal: refusing to merge unrelated histories 에러 해결법 – 원인 분석부터 완벽 해결까지

🚨 도입부

Git을 사용하면서 ‘fatal: refusing to merge unrelated histories’라는 에러를 마주쳤을 때의 좌절감, 많은 개발자들이 공감하실 것입니다. 이 에러는 특히 서로 다른 두 Git 저장소를 병합하려 할 때 발생하며, 처음 Git을 접하는 초보 개발자들에게는 더욱 혼란스러울 수 있습니다. 예를 들어, 로컬 프로젝트를 GitHub의 새로운 저장소에 푸시하려 할 때, 두 개의 서로 다른 프로젝트를 하나로 합치려 할 때, 또는 기존 프로젝트에 새로운 시작점을 추가하려 할 때 자주 나타납니다. 이 글을 통해 이 에러를 해결하는 구체적인 방법들을 배우고, 에러 발생의 근본적인 원인을 이해하며, 이를 피하기 위한 예방책까지 알아보겠습니다. 해결 과정은 복잡해보일 수 있지만, 이 글을 따라가면 10분 내외로 해결할 수 있으며, 난이도는 중급 정도로 보시면 됩니다.

🔍 에러 메시지 상세 분석

먼저, ‘fatal: refusing to merge unrelated histories’라는 정확한 에러 메시지를 살펴보겠습니다. 이 에러는 두 개의 서로 다른 이력(history)을 가진 Git 저장소를 병합하려 할 때 발생합니다. 이 에러는 주로 다음과 같은 상황에서 발생할 수 있습니다:

• 로컬 저장소를 GitHub에 처음으로 푸시하려 할 때
• 두 개의 별도의 프로젝트를 하나로 합치려 할 때
• 프로젝트 초기화나 클론 과정 중 실수로 인해 서로 다른 이력으로 설정되었을 때
• 기존 저장소에 새로운 브랜치를 추가한 후 잘못된 병합을 시도할 때
• 분기점 없이 서로 다른 두 커밋을 병합하려 할 때

에러 메시지에서 ‘fatal’은 심각한 문제가 발생했음을 의미하며, ‘refusing to merge’는 Git이 현재 병합을 거부했음을 나타냅니다. ‘unrelated histories’는 두 저장소가 서로 다른 이력을 갖고 있어 병합이 불가능하다는 뜻입니다. 초보자라면, 이 메시지를 읽고 문제의 원인을 추적하는 것이 중요합니다. 이와 비슷한 에러로 ‘fatal: not a git repository’가 있으며, 이는 저장소 초기화 과정에서 발생할 수 있는 다른 유형의 에러입니다.

🧐 발생 원인 분석

이 에러의 주요 원인들을 하나씩 살펴보겠습니다. 첫 번째로, 로컬 저장소와 원격 저장소의 초기화 시점이 다를 경우 발생할 수 있습니다. 이는 일반적으로 두 저장소가 서로 다른 ‘커밋 역사’를 가지게 되는 경우입니다. 두 번째로, 서로 다른 프로젝트를 병합하려 할 때, 각 프로젝트의 이력이 다르기 때문에 발생합니다. 세 번째로, Git 초기화 과정에서 실수로 인해 별도의 이력이 생성될 수 있습니다. 네 번째로, 기존 프로젝트에 새로운 이력 지점을 추가하면서 기존 브랜치와 충돌이 발생할 수 있습니다. 다섯 번째로, 프로젝트를 복제하거나 이동하는 과정에서 잘못된 명령어 사용으로 인해 이력이 꼬일 수 있습니다.

이러한 원인들은 대부분 Git의 이력 관리 원리를 잘 이해하지 못하여 발생합니다. Git은 이력을 매우 중요하게 여기기 때문에, 서로 다른 이력을 가진 저장소는 기본적으로 병합이 불가능합니다. 또한, 운영체제나 Git의 버전에 따라 명령어가 다르게 동작할 수 있으며, 이는 또 다른 문제를 야기할 수 있습니다. 각 원인은 간단히 ‘git log’ 명령어를 통해 현재 이력을 확인함으로써 확인할 수 있습니다.

✅ 해결 방법

이제 이 에러를 해결하는 방법들을 살펴보겠습니다.

즉시 해결: 1분 내 적용 가능한 빠른 방법

• –allow-unrelated-histories 옵션 사용: 가장 빠르게 이 문제를 해결하는 방법입니다.

  git pull origin master --allow-unrelated-histories

  이 방법은 두 이력을 강제로 병합하게 합니다. 그러나 이 방법은 비정상적인 상황을 무시하기 때문에 주의가 필요합니다.

• 새로운 커밋을 만들고 병합하기:

  git commit --allow-empty -m "Empty commit"
  git merge another-branch

  빈 커밋을 생성하여 새로운 시작점을 만들고 병합합니다.

• 로컬 저장소 재초기화:

  rm -rf .git
  git init
  git add .
  git commit -m "Reinitialize repository"
  git remote add origin [URL]
  git push origin master

  로컬 저장소를 다시 초기화하여 문제를 해결합니다.

표준 해결: 일반적이고 안전한 해결법

• Branch 재설정:

  git checkout --orphan new-start
  git commit -m "New start"
  git merge --allow-unrelated-histories another-branch

  새로운 브랜치를 만들어 병합합니다.

• 리베이스 사용:

  git checkout master
  git rebase another-branch

  리베이스 명령어를 사용하여 이력을 재정렬합니다.

• Patch 파일 생성 및 적용:

  git format-patch master --stdout > patchfile
  patch -p1 < patchfile

  이 방법은 다른 저장소의 변경사항을 패치 파일로 만들어 적용합니다.

• Cherry-pick 사용:

  git cherry-pick commit-hash

  특정 커밋을 선택하여 병합합니다.

• Subtree 이용:

  git subtree add --prefix=subdir another-repo master

  다른 저장소를 서브디렉토리로 추가합니다.

고급 해결: 복잡한 상황을 위한 해결법

• 다중 리모트 설정:

  git remote add repo1 [URL1]
  git remote add repo2 [URL2]
  git fetch repo1
  git fetch repo2
  git merge repo1/master --allow-unrelated-histories

  여러 리모트를 설정하여 병합합니다.

• Git Filter-branch:

  git filter-branch --tree-filter 'rm -rf path/to/remove' HEAD

  불필요한 파일을 제거하면서 이력을 정리합니다.

• Git bisect:

  git bisect start
  

  문제의 원인을 추적하여 원인을 제거하고 병합합니다.

이러한 방법들은 각각의 상황에 맞게 사용되어야 하며, 각 방법에는 장단점이 있습니다. 예를 들어, --allow-unrelated-histories 옵션은 강제로 병합을 시도하기 때문에 이후에 발생할 수 있는 충돌을 미리 알고 있어야 합니다. 해결 후에는 'git log'를 통해 이력이 정상적으로 병합되었는지 확인하는 것이 중요합니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러를 예방하기 위해서는 다음과 같은 방법들을 고려할 수 있습니다. 우선, 저장소 초기화 시점과 초기 커밋을 명확히 관리하여 서로 다른 이력을 만들지 않도록 합니다. 또한, 병합 전에는 항상 'git log'를 통해 이력을 확인하고, 예상치 못한 병합이 발생하지 않도록 주의합니다. 코드 리뷰 과정에서 병합 전략을 공유하고, 팀 내에서 Git 사용 가이드를 문서화하여 공유합니다. 자동화된 테스트와 린터를 사용하여 이력 관리의 일관성을 유지하는 것도 좋은 방법입니다.

🎯 마무리 및 추가 팁

이 글에서 다룬 핵심 내용은 다음과 같습니다: 1) 'fatal: refusing to merge unrelated histories' 에러의 원인 분석, 2) 다양한 해결 방법들, 3) 에러 예방을 위한 베스트 프랙티스. 비슷한 에러로 'fatal: not a git repository'를 참조할 수 있으며, 공식 Git 문서나 Stack Overflow에서 더 많은 정보를 찾아볼 수 있습니다. 이 에러로 인해 좌절하지 마세요. Git은 복잡하지만, 여러분은 충분히 해결할 수 있습니다. 함께 해결해 나갑시다!