git push 명령어 실행 후 빨간 에러가 떴을 때 30초 안에 진단하고 해결하는 흐름을 정리했습니다. 비전공자분이 가장 자주 만나는 7가지 에러 + 1줄 해결 명령, 충돌의 본질을 한 그림으로 이해하기, force push 안 쓰고 안전하게 해결하는 5단계까지. 같은 에러로 협업이 멈추는 일이 사라지도록 빠른 참조용 가이드입니다.
📑 목차
🎯 git push가 비전공자 두 번째 벽인 이유
비전공자분이 npm install 이후 두 번째로 자주 막히는 곳이 git push예요. 처음에는 잘 됐는데 어느 날 갑자기 빨간 글씨로 “rejected”가 뜨고, 영문 메시지를 읽다가 검색해도 답이 어렵게 나오는 영역입니다. 다행히 비전공자분이 마주치는 push 에러의 90%는 7가지 패턴 안에 들어와요.
이 글에서는 그 7가지 패턴 + 충돌의 본질을 한 그림으로 이해하는 흐름 + 안전한 5단계 해결까지 정리했어요. 본문 마지막에 force push 같은 위험 명령을 쓰지 않고도 거의 모든 충돌을 해결하는 방법을 다룹니다.
한 가지 미리 짚고 가겠습니다. git push 에러는 거의 항상 “협업”의 신호예요. 본인 컴퓨터와 GitHub의 리모트 상태가 어긋났다는 뜻이거든요. 그래서 해결법의 절반은 “어떻게 명령을 쓰느냐”가 아니라 “어떤 흐름으로 협업하느냐”에 있습니다. Git 기초 자체가 처음이면 GitHub 가입과 첫 저장소 만들기를 먼저 보고 오시면 좋아요.
🔍 push 충돌의 본질 — 한 그림으로
대부분의 push 에러는 한 가지 본질로 환원돼요. “내 컴퓨터(Local)”와 “GitHub(Remote)”가 서로 다른 변경을 가지고 있을 때 발생합니다. 한 그림으로 보시면 평생 가는 이해가 잡혀요.
왜 이런 일이 생기나
본인이 작업 시작 전 마지막으로 pull한 시점 이후에 GitHub의 같은 브랜치에 새 변경이 생기면, 본인 컴퓨터의 history와 GitHub의 history가 어긋납니다. 이 어긋남을 “non-fast-forward”라고 부르고, Git이 자동으로 합치지 못하니 push를 거부해요. 가장 흔한 시나리오 4가지는 다음과 같습니다.
- 다른 컴퓨터에서 push한 본인의 작업 — 노트북에서 push한 뒤 데스크톱에서 pull 안 받고 push 시도
- 다른 사람이 같은 브랜치에 push — 협업 중 가장 흔함
- GitHub 웹에서 직접 README 편집 — 본인이 무심코 한 변경이 충돌 원인
- Pull Request 머지 후 본인이 pull 안 받음 — 머지 직후 같은 브랜치에 새 작업 push
4가지 모두 해결법은 같아요. git pull로 리모트 변경을 먼저 받아온 뒤 다시 push 하시면 됩니다. 이 한 줄 흐름이 push 에러 해결의 80%를 커버해요.
⚠️ 가장 자주 만나는 7가지 에러 + 해결
비전공자분이 첫 6개월에 마주치는 push 에러를 빈도순으로 7개 정리했어요. 키워드만 알면 30초 안에 진단할 수 있습니다.
1. non-fast-forward / rejected
가장 흔한 에러. 본인 브랜치보다 리모트가 더 새 상태일 때 발생해요.
git pull origin main
# 충돌 시 → 해결 후 다시
git push origin main
2. Authentication failed (HTTPS)
GitHub은 2021년 8월부터 HTTPS 비밀번호 인증을 폐지했어요. 그래서 본인 계정 비밀번호로는 push가 안 됩니다.
# Personal Access Token 생성 (GitHub Settings → Developer settings)
# 그 후 push 시 비밀번호 자리에 토큰 붙여넣기
# 또는 SSH로 전환
git remote set-url origin [email protected]:USER/REPO.git
3. Permission denied (publickey)
SSH로 push하는데 본인 컴퓨터의 SSH 공개 키가 GitHub에 등록 안 된 경우예요.
# SSH 키 새로 생성
ssh-keygen -t ed25519 -C "[email protected]"
# 공개 키 출력 → GitHub Settings → SSH keys에 추가
cat ~/.ssh/id_ed25519.pub
4. No upstream branch
새 브랜치를 처음 push할 때 추적할 리모트 브랜치가 없을 때 발생해요. 명령에 한 옵션 추가만으로 해결됩니다.
git push --set-upstream origin 브랜치명
# 한 번 set-upstream 해두면 그 이후엔 git push만으로 OK
5. file too large / size limit
GitHub은 한 파일 100MB·저장소 1GB 한도가 있어요. 비전공자분이 자주 부딪히는 시나리오는 동영상·큰 데이터 파일·실수로 추가한 node_modules 폴더입니다.
# .gitignore에 큰 파일 추가
echo "video.mp4" >> .gitignore
# 이미 추적 중이면 캐시에서 제거
git rm --cached video.mp4
git commit -m "remove large file"
git push큰 파일을 진짜 GitHub에 올려야 하면 Git LFS(Large File Storage)를 쓰시면 됩니다.
6. repository not found / 404
저장소 URL이 오타이거나 비공개 저장소에 본인 계정 권한이 없을 때예요.
# 현재 등록된 URL 확인
git remote -v
# URL 변경
git remote set-url origin https://github.com/USER/REPO.git비공개 저장소라면 저장소 소유자가 본인을 협업자(Collaborator)로 추가해야 push가 가능합니다.
7. Updates were rejected because the tip of your branch is behind
1번과 본질이 같지만 메시지가 다르게 보일 수 있어요. --rebase 옵션으로 깔끔하게 정리하면 좋습니다.
git pull --rebase origin main
# 충돌 발생 시 파일 편집 후
git add .
git rebase --continue
git push origin main
🛡️ 충돌 해결 안전 5단계
위 에러들을 무지성으로 force push로 해결하지 마시고 안전한 5단계 흐름을 따르세요. 협업 중인 다른 사람의 작업을 날리는 일을 막아줍니다.
1단계 — 현재 상태 확인
git status현재 어떤 파일이 변경됐는지, 어떤 브랜치인지, 커밋 안 된 변경은 없는지 확인. 이 한 줄이 모든 git 작업의 시작이에요.
2단계 — 로컬 변경 보호 (선택)
git stash아직 커밋 안 한 변경이 있으면 임시 보관. 이 변경이 pull 받을 때 충돌 원인이 될 수 있어 미리 빼두는 게 안전합니다. 변경 사항이 모두 커밋된 상태면 이 단계는 건너뛰셔도 돼요.
3단계 — 리모트 변경 받기
git pull --rebase origin main리모트의 최신 변경을 로컬에 합칩니다. --rebase 옵션은 history를 깔끔하게 만들어주는 권장 방식이에요. 충돌이 발생하면 VS Code에서 충돌 마커가 표시되고, 본인이 어떤 변경을 살릴지 직접 결정합니다.
4단계 — stash 복원 (2단계 했을 때만)
git stash pop2단계에서 보관한 변경을 다시 가져옵니다. 이때도 충돌이 날 수 있는데 마찬가지로 직접 해결하시면 돼요.
5단계 — push 재시도
git push origin main위 4단계가 정상 완료됐다면 이제 push가 성공해요. 보통 5분 안쪽에 끝납니다.
VS Code에서 충돌 발생한 파일을 열면
<<<<<<< HEAD·=======·>>>>>>> 마커가 나옵니다. 첫 블록은 본인 변경, 두 번째 블록은 리모트 변경이에요. 둘 중 하나만 남기거나 둘을 합쳐서 쓰시고, 마커 줄들은 모두 삭제하시면 됩니다. VS Code의 “Accept Current/Incoming/Both Changes” 버튼을 클릭하시면 더 빠르게 해결돼요.
🔐 인증 에러 — HTTPS vs SSH
비전공자분이 가장 자주 헷갈리는 영역이 인증이에요. HTTPS와 SSH 두 가지 방식이 있고, 각각의 특성이 다릅니다.
| 항목 | HTTPS | SSH |
|---|---|---|
| URL 형태 | https://github.com/... |
[email protected]:... |
| 설정 난이도 | ★☆☆ 쉬움 | ★★☆ 키 생성 필요 |
| 인증 | Personal Access Token | SSH 키 쌍 |
| 회사 방화벽 | 대부분 허용 | 가끔 차단 |
| 편의성 | 토큰 만료 시 재발급 | 한 번 설정 후 영구 |
비전공자분 첫 시작은 HTTPS + Personal Access Token이 무난합니다. 한 번 익숙해진 뒤 SSH로 옮기시면 매번 토큰 입력이 사라져 편해져요.
HTTPS + Personal Access Token 설정
- GitHub 우측 상단 본인 아이콘 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
- Note에 본인 식별용 이름 입력 (예: “MacBook Air”)
- Expiration은 90일 또는 1년으로 설정
- Scopes에서
repo체크 - Generate 클릭 → 화면에 표시되는 토큰을 복사 (한 번만 보임, 안전한 곳에 저장)
- git push 시 비밀번호 자리에 이 토큰 붙여넣기
한 번 입력하면 OS 키체인에 저장돼서 그 이후엔 자동 인증됩니다.
SSH 키 설정 (한 번만)
# 1. 키 생성
ssh-keygen -t ed25519 -C "[email protected]"
# 2. 공개 키 출력 (private key는 절대 공유 금지)
cat ~/.ssh/id_ed25519.pub
# 3. 출력된 ssh-ed25519... 전체를 복사
# 4. GitHub Settings → SSH and GPG keys → New SSH key → 붙여넣기
# 5. 저장소의 remote URL을 SSH로 변경
git remote set-url origin [email protected]:USER/REPO.git한 번 설정하면 Personal Access Token 갱신·관리 부담이 사라져요. 본인 컴퓨터 1~2대만 쓰신다면 SSH가 장기적으로 더 편합니다.
🚫 절대 하지 말아야 할 3가지
빠르게 해결하려다 더 큰 문제를 만드는 3가지 패턴이 있어요. 한 번이라도 들어가면 협업이 통째로 무너집니다.
1. force push 무지성 사용
git push --force는 리모트의 history를 본인 로컬로 통째로 덮어써요. 협업 중인 다른 사람의 작업이 흔적도 없이 사라질 수 있습니다. 본인 혼자 쓰는 사이드 저장소가 아니면 절대 쓰지 마세요. 위 5단계 흐름으로 거의 모든 충돌이 해결됩니다.
2. .env 파일·비밀 키 push
API 키·비밀번호·결제 정보가 담긴 .env 파일을 실수로 push하면 영구 노출됩니다. .gitignore에 .env 추가는 첫 커밋 전에 반드시 해두세요. 이미 push했다면 즉시 키를 폐기하고 새로 발급받아야 안전합니다. .env 파일 관리 가이드를 같이 보시면 도움돼요.
3. main 브랜치에 직접 push (협업 중)
혼자 작업할 때는 main에 직접 push해도 OK이지만, 협업이 시작되면 별도 브랜치를 만들고 Pull Request로 머지하는 흐름이 표준이에요. main 직접 push 정책을 GitHub 저장소 설정에서 잠그면 실수를 자동으로 막을 수 있습니다.
💡 push 에러 예방 5가지 습관
에러를 빠르게 해결하는 것보다 애초에 안 만나는 게 가장 효율적이에요. 5가지 습관이 push 에러 빈도를 절반 이하로 줄여줍니다.
| # | 습관 | 효과 |
|---|---|---|
| 1 | 작업 시작 전 git pull 먼저 | 충돌 50% 감소 |
| 2 | 새 기능마다 별도 브랜치 | main 충돌 영구 차단 |
| 3 | 매일 한 번 이상 push | 충돌 규모 작아짐 |
| 4 | .gitignore 첫 커밋 전 설정 | 큰 파일·비밀 키 사고 차단 |
| 5 | commit 메시지 한 줄로 명확히 | 충돌 해결 시 빠른 판단 |
특히 1번과 2번이 가장 효과 큽니다. “pull 먼저, push 나중” + “main 직접 작업 금지”만 지켜도 푸시 에러의 70%가 사라져요.
🌐 GitHub Desktop 같은 GUI 도구는?
비전공자분이 자주 묻는 질문 중 하나가 “터미널 명령어 대신 GUI 도구 써도 되나요?”예요. 결론부터 말씀드리면 가능하고, 처음에는 오히려 권장합니다.
| 도구 | 난이도 | 장점 | 단점 |
|---|---|---|---|
| GitHub Desktop | ★☆☆ | 가장 단순, 공식 도구 | 고급 기능 제한적 |
| VS Code 내장 Git | ★★☆ | 코드 편집·커밋 한 화면 | complex 명령은 어려움 |
| SourceTree | ★★☆ | 시각화 강함 | 무거움, 가입 필요 |
| 터미널 (git CLI) | ★★★ | 모든 기능, 자동화 가능 | 학습 곡선 |
비전공자 첫 3개월은 GitHub Desktop 또는 VS Code 내장 Git으로 시작하시는 게 무난해요. 그 후 본격 사용 단계에서 터미널로 옮기시면 자동화·복잡한 작업까지 가능해집니다. GUI를 써도 위 본문의 에러 패턴은 동일하게 발생하니, 에러 메시지 키워드를 알아두시는 게 어떤 도구를 쓰든 도움됩니다.
🪧 면책 조항
오늘 안에 본인 저장소에서 git status를 한 번 실행해보세요. 그 한 줄이 push 에러의 70%를 미리 막아주는 가장 작은 습관입니다.
❓ FAQ
질문을 누르면 답변이 펼쳐집니다.
🔰 시작하기 전 궁금한 것들
Q. 비밀번호 인증이 안 되는 게 정상인가요?
Q. Personal Access Token은 어디에 저장하나요?
Q. 회사에서 SSH가 막힙니다
🛠 작업 중 자주 마주치는 상황
Q. git pull 했더니 충돌이 많이 나서 무서워요
Q. force push 한 번 했는데 동료 작업이 사라졌어요
git reflog로 이전 history를 찾아 복구할 수도 있어요. 다음부터 협업 중 force push는 절대 쓰지 마세요.Q. .env 파일을 실수로 push했습니다
git rm --cached .env로 추적 제거, 새 commit·push. 이미 GitHub에 한 번 노출된 시크릿은 영구 노출로 간주해야 안전합니다. .env 파일 관리 가이드를 참고하세요.Q. 큰 파일을 commit해서 push가 막힙니다
git rm --cached 큰파일로 추적에서 제거 + .gitignore에 추가 + 새 commit. 이미 history에 박혀 있다면 git filter-branch나 git filter-repo로 history를 다시 써야 하는데 복잡해요. 협업 안 하는 사이드 저장소면 차라리 새 저장소를 만들어 깨끗하게 시작하시는 게 빠릅니다.
🚀 그 다음 단계
Q. main 브랜치 보호는 어떻게 설정하나요?
Q. Pull Request 흐름은 어떻게 시작하나요?
Q. 같은 push 에러를 반복해서 만나요
🔗 관련 글
- GitHub 가입과 첫 저장소 만들기
- npm install 에러 해결 총정리
- .env 파일이란? API 키 안전하게 관리하기
- 바이브코딩 Git 설치 5분 완료 가이드
- GitHub 프로필 꾸미기 — 포트폴리오 활용
📑 참고 자료
IT 기획 10년차 / 비전공자를 위한 바이브코딩 블로그 운영 / vibe-start.com 제작
Building VibeStart — the fastest path for non-devs into AI coding. Launching on Product Hunt 2026-05-26.
