GitHub 저장소 초기화 오류 해결 방법과 5단계 복구 절차

오류 문구·화면 상태와 즉시 확인할 항목

GitHub 웹 UI에서 README.md, .gitignore, LICENSE 파일을 지정해 저장소를 생성한 후 로컬 커밋을 강제로 푸시하려 하면 [rejected - non-fast-forward] 또는 fatal: refusing to merge unrelated histories 오류가 발생합니다. 원격 저장소에 이미 초기 커밋이 존재하여 로컬 커밋의 뿌리(Ancestor)와 연결되지 않기 때문입니다.

이러한 충돌 현상은 GitHub CLI인 gh repo create 명령을 사용할 때 --clone 옵션을 누락하거나 웹 UI 상에서 기성 템플릿(Template)을 적용한 직후에 자주 확인됩니다. 작업을 진행하기 전 명령줄에서 git status 및 git remote -v 명령을 입력해 원격 주소 연결 상태와 현재 스테이징된 파일 목록을 먼저 점검합니다.

원인을 구분하는 4행 이상의 진단표

오류의 주요 원인을 정확히 파악해야 불필요한 커밋 손실을 방지할 수 있습니다. 아래 상태표를 바탕으로 현재 터미널에 출력된 메시지를 대조합니다.

메뉴·값·확인 상태가 포함된 5단계 이상 복구 절차

원격 저장소의 초기 파일과 로컬 프로젝트를 안전하게 동기화하고 푸시 오류를 해결하는 단계별 절차입니다.

1. 로컬 프로젝트의 루트 디렉터리에서 명령줄 터미널을 열고 git status 명령을 입력해 추적되지 않은 파일 상태를 점검합니다.
2. 현재 디렉터리에 로컬 Git 이력이 없다면 git init 명령을 실행해 저장소를 초기화하고 git branch -M main 명령으로 기본 브랜치명을 main으로 설정합니다.
3. git remote add origin https://github.com/사용자계정/저장소명.git 명령을 입력하여 GitHub 원격 주소를 로컬에 연결합니다.
4. 원격 저장소의 README.md 및 LICENSE 커밋을 로컬에 병합하기 위해 git pull origin main --allow-unrelated-histories 명령을 실행합니다.
5. 충돌이 발생한 파일이 있다면 터미널 안내에 따라 해당 파일을 수정한 후 git add . 및 git commit -m "Fix merge conflict" 명령을 실행하여 커밋을 완료합니다.
6. 터미널에 git push -u origin main 명령을 입력하여 로컬 브랜치의 모든 내역을 원격 저장소로 상향 이전합니다.

정상화 여부를 검증할 화면과 값

복구 절차가 완료되면 터미널 화면에 Everything up-to-date 또는 branch 'main' set up to track 'origin/main' 메시지가 정상적으로 출력됩니다. 이 값이 표시되면 로컬과 원격의 브랜치 추적 관계가 완전히 수립된 상태입니다.

웹 브라우저로 해당 GitHub 저장소 주소에 접속하여 새로고침을 수행합니다. 로컬에서 생성한 파일들과 웹 UI에서 추가했던 README.md 파일이 하나의 커밋 목록에 순차적으로 나열되어 있다면 정상적으로 초기화가 완료된 것입니다.

해결되지 않을 때 공식 지원에 전달할 정보와 대체 경로

네트워크 접근 권한 문제나 조직(Organization) 정책으로 인해 푸시가 지속적으로 거부되는 경우에는 계정 권한 점검이 필요합니다. 조직 계정으로 로그인한 경우에는 관리자 콘솔에서 저장소 생성 및 푸시 권한 정책을 먼저 확인합니다.

문제가 해결되지 않아 GitHub Support에 문의를 등록할 때는 발생한 전체 오류 로그, git remote -v 출력 결과, 사용 중인 Git 버전을 함께 전달합니다. 커밋 이력을 유지할 필요가 없는 신규 프로젝트라면 로컬의 .git 폴더를 삭제한 후 GitHub Desktop 프로그램을 이용하여 Clone repository 메뉴를 통해 저장소를 다시 내려받는 대안 경로를 선택합니다.