깃허브 사용법 초보 완전정복: 첫 저장소 만들기부터 에러 해결까지

깃허브, 왜 다들 쓰라고 할까

개발 공부를 시작하면 가장 먼저 듣는 말이 “일단 깃허브부터 만드세요”입니다. Git은 파일 변경 이력을 기록하고 관리하는 버전 관리 시스템이고, GitHub는 그 Git 저장소를 인터넷에 올려 공유하고 협업할 수 있게 해주는 플랫폼입니다. 2008년에 설립된 이 서비스는 2018년 Microsoft에 인수되어 지금도 Microsoft 자회사로 운영되고 있습니다.

문제는 대부분의 입문 콘텐츠가 “잘 되는 흐름”만 보여준다는 점입니다. 실제로는 설치 단계부터 막히고, 저장소 연결에서 에러가 나고, 로그인이 갑자기 안 되는 경험을 다들 한 번씩 겪습니다. 이 글은 그 막히는 지점을 중심으로 정리했습니다.

1단계: Git 설치와 GitHub 계정, 이 둘부터 구분하기

가장 흔한 초보 혼동이 여기서 시작됩니다. Git은 내 컴퓨터에 설치하는 프로그램이고, GitHub는 웹사이트(계정)입니다. 둘은 다른 존재이고, 각자 따로 준비해야 합니다.

Git 설치하기

• Git 공식 사이트에서 운영체제에 맞는 설치 파일을 내려받아 설치합니다.
• 설치가 끝나면 터미널(또는 Git Bash)에서 git --version 명령으로 설치를 확인합니다.
• 이어서 사용자 정보를 등록합니다.

git config --global user.name "본인이름"
git config --global user.email "본인이메일@example.com"

이 단계를 건너뛰면 나중에 커밋할 때 “Please tell me who you are”라는 에러가 뜹니다. 초보자 상당수가 이걸 로그인 문제로 착각하는데, 사실은 단순히 사용자 정보 설정을 안 한 것뿐입니다. 위 명령어 두 줄만 실행하면 바로 해결됩니다.

GitHub 계정 만들기

github.com에서 계정을 생성하고 이메일 인증을 완료합니다. 계정은 Git 설치와 완전히 별개의 절차이니, “Git 설치했으니 자동으로 GitHub 로그인도 될 것”이라는 오해는 하지 않는 게 좋습니다.

2단계: 새 저장소 만들기 (윈도우·VS Code 공통)

GitHub 웹사이트 우측 상단 프로필 메뉴에서 New repository를 선택합니다.

입력 항목	설명
Repository name	저장소 이름 (영문 권장)
Description	선택 사항, 프로젝트 간단 설명
Public / Private	공개 여부 (개인 무료 계정도 둘 다 무제한 생성 가능)
Initialize with README	체크 여부에 따라 이후 절차가 달라짐 (아래 주의사항 참고)

여기서 반드시 기억할 점 하나: README 초기화 옵션을 켜고, 동시에 로컬에서도 git init을 하면 문제가 생깁니다. 웹에서 만든 히스토리와 로컬 히스토리가 서로 달라 push 시 “non-fast-forward”나 “divergent histories” 충돌이 발생하기 때문입니다. 처음 시작하는 프로젝트라면 아래 둘 중 하나만 선택하세요.

• 로컬 프로젝트가 이미 있다면: README 체크 해제, 빈 저장소로 생성
• 처음부터 새로 시작한다면: README 체크, 이후 git clone으로 받아서 작업

3단계: 로컬 저장소와 GitHub 연결하기

기존 프로젝트 폴더가 있는 경우

cd 프로젝트폴더
git init
git add .
git commit -m "첫 커밋"
git branch -M main
git remote add origin <저장소 URL>
git push --set-upstream origin main

여기서 초보자가 자주 만나는 에러 두 가지를 짚어야 합니다.

① fatal: remote origin already exists

같은 이름(origin)으로 remote를 두 번 추가하면 발생합니다. 기존 remote를 확인·삭제 후 다시 추가하세요.

git remote -v
git remote remove origin
git remote add origin <저장소 URL>

② src refspec master does not match any

과거 튜토리얼은 기본 브랜치명으로 master를 썼지만, 현재 GitHub는 main을 기본 브랜치로 사용합니다. 오래된 글을 따라 하다 이 에러를 만나는 경우가 매우 흔합니다. git branch -M main으로 브랜치명을 먼저 맞춰준 뒤 push하면 해결됩니다.

저장소 URL 복사할 때 주의점

저장소 페이지의 Code 버튼을 눌러 HTTPS 또는 SSH 주소를 복사해야 합니다. 브라우저 주소창 URL을 그대로 복사해 붙여넣으면 인증 팝업조차 뜨지 않고 조용히 실패하는 경우가 있으니, 반드시 Code 버튼에서 제공하는 주소를 사용하세요.

4단계: 로그인이 안 될 때 — Personal Access Token(PAT)

“예전엔 비밀번호로 push가 됐는데 갑자기 안 된다”는 질문이 굉장히 많습니다. GitHub는 비밀번호 기반 Git 인증을 중단하고 Personal Access Token(PAT) 방식으로 전환했습니다. 정확한 정책 변경 시점은 GitHub 공식 문서에 명시적으로 표기되어 있지 않으므로, 최신 정책은 GitHub Docs의 인증 관련 섹션을 직접 확인하는 것이 가장 정확합니다.

PAT 사용 시 흔한 실수 두 가지:

• 한 번만 보여주는 토큰을 저장하지 않고 창을 닫아버림 → 다시 확인 불가, 새로 발급해야 함
• 토큰 생성 시 repo 권한 스코프를 체크하지 않음 → push가 거절됨, 원인을 모른 채 “깃허브가 안 된다”고만 생각하게 됨

토큰을 발급받으면 안전한 곳(비밀번호 관리자 등)에 즉시 저장해두고, push 시 비밀번호 입력란에 이 토큰을 입력하면 됩니다.

5단계: 기본 작업 흐름 — add, commit, push의 차이

초보자가 가장 헷갈려하는 개념이 “파일 저장 = GitHub 업로드”라는 착각입니다. 실제로는 3단계를 거쳐야 합니다.

• git add: 변경사항을 커밋 대상으로 등록 (스테이징)
• git commit: 등록된 변경사항을 로컬 저장소에 기록
• git push: 로컬 기록을 GitHub(원격 저장소)로 전송

이 중 하나라도 빠지면 “분명 저장했는데 GitHub에 안 보인다”는 상황이 생깁니다. git status 명령으로 지금 어느 단계인지 항상 확인하는 습관을 들이면 문제 추적이 훨씬 쉬워집니다.

6단계: 브랜치와 Pull Request로 협업하기

개인 프로젝트는 main 브랜치에 바로 push해도 되지만, 팀 프로젝트나 오픈소스 참여에서는 브랜치를 나눠 작업하고 Pull Request(PR)로 병합하는 것이 기본 흐름입니다.

git checkout -b feature-이름
(작업 후)
git add .
git commit -m "작업 내용"
git push origin feature-이름

이후 GitHub 웹에서 Pull Request를 생성하고, 리뷰를 거쳐 Merge합니다. “PR을 만들었는데 코드가 반영이 안 된다”는 질문은 대부분 PR이 아직 머지되지 않았거나, 엉뚱한 브랜치를 대상으로 PR을 만든 경우입니다.

일부 조직·프로젝트는 main 브랜치에 직접 push를 막아두는 Protected Branch 규칙을 적용합니다. 이 경우 git push origin main이 거절되며, 반드시 PR을 통해서만 병합할 수 있습니다.

Fork와 Clone은 다르다

오픈소스 프로젝트에 기여할 때 Fork와 Clone을 혼동하는 경우가 많습니다. Fork는 다른 사람의 저장소를 내 계정으로 복사해오는 것이고, Clone은 저장소를 내 컴퓨터로 내려받는 것입니다. Fork했다고 원본 저장소와 자동으로 동기화되지 않으며, 별도로 동기화 작업을 해줘야 합니다.

유니티에서 깃허브 사용법이 궁금하다면

유니티(Unity) 프로젝트는 바이너리 파일(씬, 에셋)이 많아 일반 코드 프로젝트와 Git 사용법이 조금 다릅니다. 핵심은 .gitignore 설정으로 Library/, Temp/, Obj/ 등 자동 생성 폴더를 제외하는 것입니다. 기본적인 add-commit-push 흐름 자체는 동일하니, 위 3~5단계를 그대로 적용하면 됩니다.

GitHub Desktop으로 명령어 없이 쓰는 방법

터미널 명령어가 아직 부담스럽다면 GitHub Desktop을 추천합니다. 저장소 생성, 변경사항 커밋, origin 연결, push까지 전부 GUI 클릭만으로 처리할 수 있습니다. 다만 리베이스처럼 일부 고급 기능은 CLI에서만 지원되는 경우가 있으니, 어느 정도 익숙해지면 명령어도 함께 익혀두는 것이 좋습니다.

VS Code에서 깃허브 사용법

VS Code는 소스 제어 탭에서 git add/commit/push를 버튼 클릭만으로 처리할 수 있어 초보자 진입 장벽이 낮습니다. 좌측 소스 제어 아이콘 → 변경 파일 확인 → 커밋 메시지 입력 → 체크 표시(커밋) → Sync(push) 순서로 진행하면 됩니다. GitHub 계정과 VS Code를 연동해두면 로그인 팝업도 한 번만 처리하면 됩니다.

자주 나는 에러 요약표

에러 메시지	원인	해결
Please tell me who you are	user.name/email 미설정	git config --global 명령으로 설정
remote origin already exists	origin 중복 추가	git remote remove origin 후 재추가
src refspec master does not match any	브랜치명 master/main 불일치	git branch -M main으로 통일
Repository not found / permission denied	저장소 권한 없음 또는 Private 접근 문제	저장소 소유자에게 Write 권한 요청
non-fast-forward / divergent histories	웹 README와 로컬 히스토리 충돌	README 초기화 여부를 한쪽만 선택

자주 묻는 질문

함께 보면 좋은 글

• IT 포트폴리오 작성법, 예시로 보는 합격 포인트 총정리
• 개발자 이력서 작성법 완벽 가이드: 신입부터 경력직까지 (feat. 공공기관 블라인드 양식)
• IT 취업 로드맵, 2026년 비전공자도 통하는 현실 전략