GitHub 저장소 초기화 오류 해결: 푸시 거부 원인과 6단계 복구 절차
GitHub 저장소 초기화 중 발생하는 푸시 거부(non-fast-forward)와 이력 병합 거부(unrelated histories) 오류의 원인을 터미널 메시지로 구분하고 복구하는 절차를 설명합니다.
GitHub- 분야
- 개발도구
- 공식 자료
- 2개
- 읽는 시간
- 5분
- 최종 확인
- 2026.09.24
오류 원인 요약
GitHub 웹 UI에서 README.md, .gitignore, LICENSE 파일을 지정해 저장소를 만든 뒤 로컬 커밋을 강제로 푸시하면 [rejected - non-fast-forward] 또는 fatal: refusing to merge unrelated histories 오류가 발생합니다. 원격 저장소에 이미 초기 커밋이 있어 로컬 커밋의 뿌리(Ancestor)와 연결되지 않기 때문입니다.
이 충돌은 웹에서 README·.gitignore·라이선스를 넣어 저장소를 만든 뒤, 로컬에서 별도로 git init 한 커밋을 올릴 때 발생합니다. 작업 전에는 명령줄에서 git status와 git remote -v를 입력해 원격 주소 연결 상태와 현재 스테이징된 파일 목록을 먼저 확인해야 합니다.
터미널 메시지별 원인과 조치
원인을 정확히 파악해야 불필요한 커밋 손실을 막을 수 있습니다. 터미널에 출력된 오류 메시지별 원인, 점검 항목, 조치를 비교한 표입니다.
| 터미널 출력 오류 메시지 | 주요 원인 | 점검 항목 | 조치 방향 |
|---|---|---|---|
| fatal: refusing to merge unrelated histories | 커밋 이력이 서로 다른 두 저장소의 병합 시도 | git log 명령으로 로컬/원격 커밋 트리 비교 | --allow-unrelated-histories 플래그 사용 |
| error: failed to push some refs to | 원격 저장소에 로컬에 없는 최신 커밋 존재 | git fetch origin 후 원격 변경 사항 확인 | git pull 또는 rebase 적용 후 푸시 |
| fatal: remote origin already exists | 다른 원격 주소가 이미 origin으로 등록됨 | git remote -v로 등록된 URL 조회 | git remote remove origin 후 재등록 |
| error: src refspec main does not match any | 로컬에 커밋 내역이 없거나 브랜치명이 다름 | git branch 명령으로 현재 브랜치명 확인 | git commit 작성 또는 브랜치명 변경 |
복구 절차
원격 저장소의 초기 파일과 로컬 프로젝트를 동기화하고 푸시 오류를 해결하는 절차는 다음과 같습니다.
- 로컬 프로젝트의 루트 디렉터리에서 터미널을 열고 git status를 입력해 추적되지 않은 파일 상태를 확인합니다.
- 현재 디렉터리에 로컬 Git 이력이 없다면 git init으로 저장소를 초기화하고, git branch -M main으로 기본 브랜치명을 main으로 설정합니다.
- git remote add origin https://github.com/사용자계정/저장소명.git 명령을 입력해 GitHub 원격 주소를 로컬에 연결합니다.
- 원격 저장소의 README.md 및 LICENSE 커밋을 로컬에 병합하기 위해 git pull origin main --allow-unrelated-histories 명령을 실행합니다.
- 충돌이 발생한 파일이 있으면 터미널 안내에 따라 파일을 수정한 뒤 git add . 및 git commit -m "Fix merge conflict" 명령을 실행해 커밋을 완료합니다.
- git push -u origin main 명령을 입력해 로컬 브랜치의 모든 내역을 원격 저장소로 올립니다.
푸시 완료 확인
복구 절차가 끝나면 터미널에 Everything up-to-date 또는 branch 'main' set up to track 'origin/main' 메시지가 출력됩니다. 이 메시지가 표시되면 로컬과 원격 브랜치의 추적 관계가 설정된 것입니다.
웹 브라우저에서 해당 GitHub 저장소 주소를 열고 새로고침합니다. 로컬에서 만든 파일과 웹 UI에서 추가한 README.md가 하나의 커밋 목록에 순서대로 표시되면 초기화가 완료된 것입니다.
권한 확인과 GitHub Support 문의
네트워크 접근 권한이나 조직(Organization) 정책 때문에 푸시가 계속 거부되는 경우에는 계정 권한을 점검해야 합니다. 조직 계정으로 로그인한 경우에는 관리자 콘솔에서 저장소 생성 및 푸시 권한 정책을 먼저 확인합니다.
문제가 해결되지 않아 GitHub Support에 문의할 때는 전체 오류 로그, git remote -v 출력 결과, 사용 중인 Git 버전을 함께 전달합니다. 커밋 이력을 유지할 필요가 없는 신규 프로젝트라면, 로컬의 .git 폴더를 삭제한 뒤 GitHub Desktop의 Clone repository 메뉴로 저장소를 다시 내려받는 방식을 대안으로 사용할 수 있습니다.
이 글의 수정 내역 · 2026-09-24
2026-09-24 정정: 근거 없는 'gh repo create --clone 누락' 원인 문장을 실제 발생 조건으로 교체, 제목의 단계 수를 본문(6단계)과 일치시키고 무관 출처 10건 제거.
참고한 출처
docs.github.com — Quickstart for repositories (2026-08-19)
docs.github.com — Create a new repository (2026-08-19)
공식 문서 확인