git push 에러 src refspec master does not match any 에러 해결법｜원인 3가지 진단법

git push를 했는데 아래 메시지가 나오고 아무것도 올라가지 않는 경우입니다.

error: src refspec master does not match any
error: failed to push some refs to 'github.com:USERNAME/REPOSITORY.git'

“보내라고 한 master라는 브랜치를 로컬에서 찾을 수 없다”는 뜻입니다. 네트워크나 권한 문제가 아니라 로컬 저장소 상태의 문제입니다. 그래서 여러 번 다시 시도하거나 --force를 붙여도 결과가 똑같습니다.

git push --force origin master   # 이래도 같은 에러가 납니다

30초 진단 — 명령어 한 줄로 원인 가리기

원인은 세 가지인데 에러 메시지는 하나뿐입니다. 그래서 해결법을 검색해도 자기 상황과 안 맞는 답이 나옵니다. 아래 한 줄이면 어느 쪽인지 바로 갈립니다.

git status --short --branch

첫 줄에 나오는 것	원인
## No commits yet on main	원인 1 · 커밋이 하나도 없음
## main 등 master가 아닌 이름	원인 2 · 브랜치 이름 불일치
## master 인데도 에러	원인 3 · 오타 또는 원격 설정

원인 1 — 커밋이 하나도 없다

가장 흔한 경우입니다. git add까지만 하고 git commit을 하지 않은 상태입니다.

git은 커밋이 있어야 브랜치가 만들어집니다. 파일을 add만 해둔 상태에서는 브랜치가 아직 존재하지 않기 때문에, 보낼 대상 자체가 없습니다.

$ git status --short --branch
## No commits yet on main
A  a.txt

No commits yet이 보이면 이 경우입니다. 커밋을 한 번 만들면 해결됩니다.

git commit -m "first commit"
git push -u origin main

참고로 커밋이 없을 때는 git log도 이렇게 답합니다. 이것도 같은 신호입니다.

$ git log --oneline
fatal: your current branch 'main' does not have any commits yet

원인 2 — 브랜치는 main인데 master로 push했다

커밋을 제대로 했는데도 이 에러가 난다면 대부분 이 경우입니다.

2020년 10월부터 GitHub에서 새로 만드는 저장소의 기본 브랜치 이름이 master에서 main으로 바뀌었습니다. git 자체도 2.28 버전부터 기본 이름을 지정할 수 있게 됐고, 요즘 설치본은 대부분 main으로 만들어집니다.

그런데 인터넷에 남아 있는 예전 튜토리얼들은 여전히 이렇게 알려줍니다.

git push -u origin master

로컬 브랜치는 main인데 master를 보내라고 하니, git 입장에서는 “그런 브랜치 없다”가 됩니다. 현재 브랜치 이름부터 확인하세요.

$ git branch --show-current
main

반대 경우도 있습니다. 브랜치가 master인데 git push origin main을 하면 src refspec main does not match any가 납니다. 이름만 바뀌었을 뿐 원인은 같습니다.

해결 A · 브랜치 이름 그대로 push (권장)

git push -u origin main

해결 B · 브랜치 이름을 master로 바꾸기

git branch -M master
git push -u origin master

원격 저장소가 이미 main을 쓰고 있다면 A가 맞습니다. 굳이 master로 되돌릴 이유가 없고, 되돌리면 GitHub에서 기본 브랜치를 다시 지정해야 합니다.

앞으로 만들 저장소의 기본 이름을 아예 정해두려면 이렇게 설정합니다.

git config --global init.defaultBranch main

원인 3 — 브랜치 이름 오타 또는 원격 설정

커밋도 있고 브랜치 이름도 맞는데 에러가 난다면, 브랜치 목록과 원격 주소를 함께 확인합니다.

git branch -a          # 로컬·원격 브랜치 전체 보기
git remote -v          # 원격 저장소 주소 확인

git remote -v를 쳤을 때 아무것도 안 나오면 원격 저장소가 등록되지 않은 상태입니다. 이때 자주 나오는 실수가 원격 이름을 빠뜨리는 것입니다.

git remote add [email protected]:USERNAME/REPOSITORY.git          # 틀림
git remote add origin [email protected]:USERNAME/REPOSITORY.git   # 맞음

origin은 원격 저장소에 붙이는 이름입니다. 이걸 빠뜨리면 등록 자체가 되지 않습니다.

처음부터 순서대로 하는 경우

로컬에서 이미 작업을 진행한 폴더를 GitHub의 빈 저장소에 처음 올리는 상황이라면, 아래 순서 그대로 하면 이 에러를 만나지 않습니다.

# 1. 작업 폴더를 git 저장소로 만든다
git init

# 2. 변경된 파일을 전부 추가한다
git add .

# 3. 커밋한다  ← 이 단계를 빠뜨리면 원인 1의 에러가 난다
git commit -m "first commit"

# 4. 현재 브랜치 이름을 확인한다  ← 원인 2를 미리 막는다
git branch --show-current

# 5. 원격 저장소를 등록한다  (origin 을 빠뜨리지 말 것)
git remote add origin [email protected]:USERNAME/REPOSITORY.git

# 6. 4번에서 확인한 이름으로 push 한다
git push -u origin main

git init을 실행하면 해당 폴더에 .git이라는 숨김 디렉터리가 생깁니다. 여기에 모든 버전 기록이 들어갑니다.

자주 묻는 질문

Q. –force를 붙여도 왜 안 되나요?

--force는 “원격에 있는 내용을 덮어써라”는 뜻입니다. 이 에러는 보낼 것을 로컬에서 못 찾은 상태라서, 덮어쓸 내용 자체가 없습니다. 강제로 밀어붙일 대상이 없으니 결과가 같습니다.

Q. main과 master 중 뭘 써야 하나요?

기능상 차이는 전혀 없습니다. 그냥 브랜치 이름입니다. 다만 GitHub·GitLab의 새 저장소 기본값이 main이고, 새로 시작하는 프로젝트는 main을 쓰는 쪽이 표준에 가깝습니다. 기존 저장소가 master를 쓰고 있다면 굳이 바꿀 필요는 없습니다.

Q. 이미 master로 올렸는데 main으로 바꾸려면?

git branch -M main                       # 로컬 브랜치 이름 변경
git push -u origin main                  # main 으로 push
git push origin --delete master          # 원격의 master 삭제

마지막 줄을 실행하기 전에 GitHub 저장소의 Settings → Branches에서 기본 브랜치를 main으로 먼저 바꿔야 합니다. 그러지 않으면 기본 브랜치는 지워지지 않습니다.

Q. git init을 잘못했습니다. 되돌릴 수 있나요?

.git 디렉터리를 지우면 git 관리에서 완전히 빠집니다. 작업하던 파일은 그대로 남습니다.

rm -rf .git

다만 이미 커밋한 기록이 있다면 그 기록은 전부 사라집니다. 실행 전에 현재 폴더가 맞는지 pwd로 한 번 확인하세요.

Q. SSH가 아니라 HTTPS 주소를 쓰고 싶습니다

git remote add origin https://github.com/USERNAME/REPOSITORY.git

이미 등록한 주소를 바꾸려면 add 대신 set-url을 씁니다.

git remote set-url origin https://github.com/USERNAME/REPOSITORY.git

정리

진단	원인	해결
No commits yet	커밋 없음	git commit -m "first commit"
브랜치가 main	이름 불일치	git push -u origin main
브랜치는 맞음	오타·원격 미등록	git remote -v 로 확인

세 가지 모두 git status --short --branch 한 줄로 구분됩니다. 에러 메시지가 같아서 헷갈릴 뿐, 원인만 알면 해결은 명령어 한 줄입니다.

참고

• GitHub Docs · Managing remote repositories
• GitHub Blog · Renaming the default branch from master