AI & 코딩

Git 변경 사항을 GitHub에 올리는 완벽 가이드: add, commit, push의 모든 것

디지털가드너 (Digital Gardener) 2026. 6. 26. 09:46

개발을 처음 시작하거나 협업 프로젝트를 진행할 때, 가장 기본이 되면서도 헷갈리는 부분이 바로 버전 관리입니다. 내 컴퓨터(로컬)에서 열심히 작성하고 수정한 코드를 원격 저장소인 GitHub에 안전하게 반영하려면 어떻게 해야 할까요?

바쁜 분들을 위해 핵심 요약부터 말씀드리자면, 코드를 수정하고 GitHub에 올리는 과정은 다음 세 줄의 명령어로 요약할 수 있습니다.

핵심 요약: GitHub 업로드 3단계 명령어

  1. git add . (모든 변경 사항을 업로드 준비 상태로 만들기)
  2. git commit -m "작업 내용 설명" (로컬 저장소에 변경 기록 확정하기)
  3. git push origin main (GitHub 원격 저장소로 밀어 올리기)

이제부터 위 과정이 왜 필요한지, 각 명령어는 정확히 어떤 역할을 하는지, 그리고 오류가 발생했을 때는 어떻게 대처해야 하는지 초보자부터 실무자까지 모두에게 유용한 정보를 상세히 안내해 드리겠습니다.

1. Git과 GitHub, 정확한 차이점과 작동 원리 이해하기

명령어를 무작정 외우기 전에 Git의 작동 원리를 이해하는 것이 중요합니다. 많은 분이 Git과 GitHub를 헷갈리지만, 이 둘은 명확히 다른 역할을 수행합니다.

구분 Git GitHub
개념 로컬에서 파일의 변경 이력을 추적하는 '버전 관리 시스템(프로그램)' Git으로 관리되는 프로젝트를 온라인에 저장하고 공유하는 '클라우드 호스팅 서비스'
작업 환경 내 컴퓨터 (로컬 환경) 인터넷 웹 서버 (원격 환경)
주요 목적 버전 관리, 코드 백업, 로컬 브랜치 생성 협업, 코드 리뷰, 포트폴리오 관리, 오픈소스 기여

Git은 내 컴퓨터 안에서 3가지 작업 영역을 거쳐 파일을 관리합니다. 이 흐름을 이해하면 add와 commit을 왜 따로 해야 하는지 알 수 있습니다.

  1. 작업 디렉터리 (Working Directory): 현재 내가 코드를 작성하고 수정하는 실제 폴더입니다.
  2. 스테이징 영역 (Staging Area): 커밋(확정)을 하기 전, 변경된 파일들 중 이번에 기록할 파일들만 모아두는 '임시 대기실'입니다.
  3. 로컬 저장소 (Local Repository): 내 컴퓨터에 저장된 최종 버전들의 기록 보관소입니다.

우리가 코드를 GitHub(원격 저장소)에 올린다는 것은, [작업 디렉터리] → [스테이징 영역] → [로컬 저장소] → [원격 저장소(GitHub)] 순으로 데이터를 이동시키는 과정을 의미합니다.

2. 로컬 작업물을 GitHub로 업로드하는 4단계 핵심 프로세스

본격적으로 터미널이나 명령 프롬프트를 열고, 작업 중인 프로젝트 폴더로 이동한 뒤 아래의 단계들을 순서대로 실행해 보세요.

1단계: 변경된 파일 상태 확인하기 (git status)

현재 폴더에서 어떤 파일이 수정되었고, 새로 생성되었는지 확인하는 습관을 들이는 것이 좋습니다.

Bash
 
git status
  • 빨간색 파일명: 수정되었지만 아직 스테이징 영역에 올라가지 않은 파일입니다.
  • 초록색 파일명: 스테이징 영역에 성공적으로 올라가서 커밋될 준비가 된 파일입니다.

2단계: 변경 사항을 스테이징 영역에 올리기 (git add)

수정된 파일들을 커밋하기 위해 임시 대기실(스테이징 영역)에 올리는 과정입니다.

  • 모든 변경 사항을 한 번에 추가할 때 (가장 많이 사용):
  • Bash
     
    git add .
  • 특정 파일만 선택해서 추가할 때: 여러 파일을 수정했지만, 기능별로 나누어 커밋하고 싶을 때 유용합니다.
  • Bash
     
    git add index.html style.css

3단계: 로컬 저장소에 커밋하기 (git commit)

스테이징 영역에 올라온 파일들을 하나의 버전으로 확정 짓고, 어떤 작업을 했는지 메모(메시지)를 남기는 과정입니다. 이 메시지는 나중이나 다른 팀원이 코드를 볼 때 중요한 이정표가 됩니다.

Bash
 
git commit -m "여기에 변경 사항을 설명하는 메시지를 적습니다"

[참고] 실무에서 사랑받는 커밋 메시지 컨벤션(규칙)

좋은 커밋 메시지는 첫 단어만 봐도 어떤 성격의 작업인지 알 수 있어야 합니다.

  • feat: 새로운 기능 추가 (예: feat: 로그인 기능 구현)
  • fix: 버그 수정 (예: fix: 결제 버튼 클릭 오류 수정)
  • docs: 문서 수정 (예: docs: README.md 사용법 추가)
  • style: 코드 포맷팅, 세미콜론 누락 수정 (비즈니스 로직 변경 없음)
  • refactor: 코드 리팩토링 (기능 변화 없이 코드 구조 개선)

4단계: 원격 저장소인 GitHub로 푸시하기 (git push)

이제 내 컴퓨터(로컬 저장소)에 안전하게 기록된 버전들을 온라인(GitHub)으로 전송할 차례입니다.

Bash
 
git push origin main
  • origin: 내 로컬 저장소와 연결된 원격 저장소(GitHub)의 기본 별명(Alias)입니다.
  • main: 작업하고 있는 브랜치(Branch)의 이름입니다. 과거에는 master라는 이름을 기본으로 사용했으나, 최근에는 main을 표준으로 사용합니다. 만약 오류가 난다면 git branch 명령어로 현재 브랜치 이름이 master인지 main인지 확인해 보세요.

3. 실무에서 알아두면 좋은 Git 활용 팁

단순히 코드를 올리는 것을 넘어, 조금 더 프로페셔널하게 Git을 다루기 위한 팁을 소개합니다.

불필요한 파일 제외하기 (.gitignore)

비밀번호가 담긴 환경설정 파일, 용량이 너무 큰 이미지, OS에서 자동 생성되는 시스템 파일(예: .DS_Store) 등은 GitHub에 올라가면 곤란합니다. 프로젝트 최상단에 .gitignore 파일을 만들고, 무시할 파일이나 폴더의 이름을 적어두면 Git이 해당 파일들의 변경 사항을 추적하지 않습니다.

논리적인 단위로 쪼개서 커밋하기

수십 개의 파일을 한 번에 몰아서 하나의 커밋으로 남기면 나중에 문제가 생겼을 때 어디서부터 잘못되었는지 찾기 매우 힘듭니다. "회원가입 UI 작성", "회원가입 API 연동" 등 기능이나 논리적인 단위별로 자주 커밋을 남기는 것이 훌륭한 버전 관리의 핵심입니다.

4. 자주 발생하는 Git Push 오류와 완벽한 해결 방법

명령어를 정확히 쳤음에도 git push 단계에서 빨간색 에러 메시지가 쏟아지는 경우가 있습니다. 당황하지 말고 아래의 대표적인 원인과 해결책을 확인해 보세요.

오류 1: Updates were rejected because the remote contains work that you do not have locally.

  • 원인: 내 컴퓨터에는 없는 새로운 변경 사항이 GitHub(원격 저장소)에 이미 존재하기 때문입니다. 누군가 먼저 코드를 푸시했거나, 내가 GitHub 웹사이트에서 직접 파일을 수정했을 때 발생합니다.
  • 해결 방법: 원격 저장소의 최신 상태를 내 컴퓨터로 먼저 가져와서 병합(pull)한 뒤에 다시 올리면 됩니다.
  • Bash
     
    git pull origin main
git push origin main

오류 2: Permission denied (publickey) 또는 인증 오류

  • 원인: 내 컴퓨터가 해당 GitHub 저장소에 코드를 올릴 권한(인증)이 없어서 발생합니다.
  • 해결 방법: GitHub Personal Access Token (PAT)을 발급받아 비밀번호 대신 사용하거나, SSH 키를 생성하여 GitHub 계정에 등록해야 합니다.

오류 3: src refspec main does not match any

  • 원인: 로컬 저장소에 커밋된 내역이 아예 없거나, 올리려고 하는 브랜치의 이름이 잘못되었을 때 발생합니다.
  • 해결 방법: 먼저 git commit을 완료했는지 확인합니다. 커밋이 되어 있다면 브랜치 이름이 main인지 master인지 확인하고 알맞게 입력합니다.

5. 자주 묻는 질문 (FAQ)

Q. 커밋 메시지를 잘못 적었는데 수정할 수 있나요?

네, 가능합니다. 방금 완료한 가장 최신 커밋의 메시지를 수정하려면 아래 명령어를 사용하세요. 단, 아직 GitHub에 push 하기 전이어야 깔끔하게 수정됩니다.

Bash
 
git commit --amend -m "수정할 새로운 커밋 메시지"

Q. 실수로 이상한 파일까지 git add 해버렸어요. 취소하려면요?

스테이징 영역에 잘못 올린 파일은 커밋하기 전이라면 다음 명령어로 쉽게 내릴 수 있습니다.

Bash
 
git restore --staged 파일명

모든 파일의 스테이징을 한 번에 취소하고 싶다면 git reset HEAD를 입력하면 됩니다.

Q. 메인 브랜치가 아닌 개인 브랜치에 코드를 올리려면 어떻게 하나요?

협업을 할 때는 각자의 브랜치에서 작업하는 것이 원칙입니다. 예를 들어 feature-login이라는 브랜치를 만들고 코드를 올리려면 아래와 같이 실행합니다.

Bash
 
git checkout -b feature-login  # 브랜치 생성 및 이동
git add .
git commit -m "feat: 로그인 페이지 마크업 완료"
git push origin feature-login  # 생성한 브랜치 이름으로 푸시

Git과 GitHub는 처음 접할 때는 복잡하고 무섭게 느껴질 수 있지만, 익숙해지면 코드의 유실을 막고 개발 과정의 모든 역사를 체계적으로 관리해 주는 든든한 지원군이 됩니다. 오늘 안내해 드린 status, add, commit, push의 흐름을 지속적으로 실습하시면서 완벽하게 자신의 것으로 만들어 보시길 바랍니다.

저작자표시 비영리 변경금지 (새창열림)