🔥 GitHub 푸시 오류 failed to push some refs 3분 해결법

Git 푸시를 하다 보면 "failed to push some refs to"라는 빨간색 에러 메시지를 본 적이 있을 겁니다. 원격 저장소와 내 컴퓨터의 버전이 달라서 발생하는 문제인데, 생각보다 간단히 해결됩니다. 이 글에서는 이 오류가 왜 생기는지, 그리고 3분 안에 해결하는 방법을 차근차근 설명해 드리겠습니다.

이 오류, 왜 발생할까

원격 저장소(GitHub)에 내 로컬 저장소에는 없는 파일이나 커밋이 존재할 때, 푸시가 자동으로 차단됩니다. 예를 들어 이런 상황을 생각해 보세요. 팀원 B가 f2.py 파일을 원격 저장소에 올렸는데, 내 컴퓨터에는 f1.py만 있습니다. 이 상태에서 내가 f1.py를 수정하고 푸시하려고 하면 Git이 충돌을 막기 위해 거부하는 겁니다.

이 오류는 특히 다른 사람과 협업할 때 자주 발생합니다. 또 인텔리제이 같은 IDE에서 프로젝트 폴더를 윈도우 탐색기로 드래그 앤 드롭해서 옮긴 후 푸시할 때도 같은 문제가 생길 수 있습니다. 깃허브 사이트에서 직접 파일을 업로드한 경우에도 마찬가지입니다.

가장 빠른 해결법 git pull로 원격 내용 가져오기

해결 방법은 매우 단순합니다. 원격 저장소의 내용을 내 로컬로 먼저 가져온 후, 다시 푸시하면 됩니다. 기본 명령어는 다음과 같습니다.

git pull origin main

이 명령어는 원격 저장소(origin)의 main 브랜치에 있는 변경 사항을 내 로컬 브랜치로 가져와 병합합니다. 이후 git push를 다시 시도하면 정상적으로 작동합니다.

git pull 중 "fatal refusing to merge unrelated histories"가 나올 때

가끔 git pull을 실행했는데 위와 같은 메시지가 뜨면서 병합이 거부되는 경우가 있습니다. 이는 로컬 저장소와 원격 저장소의 커밋 이력이 완전히 달라서 Git이 자동 병합을 포기한 상황입니다. 이런 경우에는 아래 명령어를 사용하세요.

git pull origin main --allow-unrelated-histories

이 옵션은 서로 관련 없는 두 저장소의 이력을 강제로 병합합니다. 보통 깃허브에서 README나 라이선스 파일을 먼저 생성한 후, 로컬 저장소를 처음 푸시할 때 이런 문제가 자주 생깁니다.

병합 충돌이 발생했다면

git pull 과정에서 충돌(conflict)이 생길 수도 있습니다. 이때는 당황하지 말고 충돌이 난 파일을 열어서 직접 수정하면 됩니다. 충돌 부분은 <<<<<<<, =======, >>>>>>> 표시로 구분되어 있습니다. 수정을 마친 후에는 저장하고 다시 커밋한 뒤 푸시하세요.

강제 푸시는 신중하게 사용하세요

로컬 내용을 원격 저장소에 강제로 덮어쓰고 싶다면 git push --force 명령어를 쓸 수 있습니다. 하지만 이 방법은 원격 저장소의 기존 커밋을 삭제하므로, 혼자 작업하는 저장소가 아니라면 사용을 권장하지 않습니다. 팀원이 올린 코드가 사라질 수 있기 때문입니다.

자주 묻는 질문들

Q. git pull만 하면 되나요? 다른 방법은 없나요?

네. 대부분의 경우 git pull이 가장 권장되는 해결 방법입니다. 강제 푸시는 최후의 수단으로 생각하세요.

Q. pull 했는데도 계속 오류가 나요.

이 경우 원격 저장소에 추가 커밋이 더 있는지 확인해 보세요. git status 명령어로 현재 상태를 파악한 후, 다시 한 번 git pull을 시도해 보세요.

Q. 협업할 때 이 오류를 예방할 수 있나요?

푸시하기 전에 항상 git pull로 최신 상태를 유지하는 습관을 들이면 오류 발생을 크게 줄일 수 있습니다. 특히 푸시 직전에 pull을 한 번 더 실행하는 것이 좋습니다.