Git·GitHub 초보가 커밋과 푸시하는 법

Git은 파일 변경 이력을 기록하는 도구이고, GitHub는 그 이력을 원격 저장소에 올려 협업할 수 있게 해 주는 서비스입니다. 처음에는 add, commit, push라는 단어가 낯설지만, 실제 흐름은 간단합니다. 어떤 파일이 바뀌었는지 확인하고, 올릴 변경만 골라 임시 무대에 올리고, 의미 있는 단위로 기록한 뒤, 원격 저장소에 전송하면 됩니다.

이 글은 블로그나 작은 웹 서비스를 운영하면서 처음 Git을 쓰는 사람을 기준으로 설명합니다. Markdown 글을 추가하거나 설정 파일을 고친 뒤 배포해야 한다면 Markdown으로 기술 블로그 운영하기, 정적 사이트 배포를 준비한다면 Cloudflare Workers로 정적 사이트 배포하기와 함께 보면 좋습니다.

1. Git 작업 전 현재 위치를 확인한다

터미널을 열면 먼저 내가 어떤 폴더에 있는지 확인해야 합니다. 프로젝트 루트가 아닌 곳에서 명령을 실행하면 Git 저장소를 찾지 못하거나 엉뚱한 파일을 건드릴 수 있습니다.

pwd
git status

git status는 현재 브랜치, 수정된 파일, 새 파일, 삭제된 파일을 보여 줍니다. 초보자에게 가장 중요한 명령어는 commit보다 status입니다. 커밋하기 전에 반드시 한 번, 푸시하기 전에 다시 한 번 실행하는 습관을 들이세요.

출력에 On branch main처럼 브랜치 이름이 보이고, Changes not staged for commit 또는 Untracked files가 보이면 아직 커밋되지 않은 변경이 있다는 뜻입니다. “nothing to commit, working tree clean”이면 기록할 변경이 없습니다.

2. 변경 내용을 눈으로 확인한다

파일 이름만 보고 커밋하면 실수로 디버그 코드, 임시 메모, 비밀 키를 올릴 수 있습니다. 변경 내용을 확인하려면 다음 명령을 사용합니다.

git diff
git diff --staged

git diff는 아직 스테이지에 올리지 않은 변경을 보여 주고, git diff --staged는 커밋에 포함될 변경을 보여 줍니다. 여기서 .env, API 키, 비밀번호, 개인 이메일, 내부 URL이 보이면 커밋을 멈추고 정리해야 합니다. 민감 정보 관리는 API 키를 코드에 넣지 않는 이유와 .env 관리에서 별도로 다룹니다.

실무에서는 파일을 저장할 때 포맷터가 많은 줄을 바꿀 수 있습니다. 내가 의도한 변경보다 훨씬 많은 줄이 바뀌었다면 그대로 커밋하지 말고 원인을 확인하세요. 작은 수정 하나가 대규모 포맷 변경과 섞이면 리뷰도 어렵고 되돌리기도 어렵습니다.

3. git add는 커밋에 담을 파일을 고르는 단계다

git add는 파일을 Git에 “추적해 줘”라고 말하는 동시에, 다음 커밋에 포함할 변경으로 표시하는 명령입니다.

git add src/content/posts/new-post.md
git add src/components/Header.astro

모든 변경을 한 번에 올리고 싶을 때는 git add .를 쓰지만, 초보자라면 파일 단위로 추가하는 습관이 안전합니다. 특히 블로그 글, 설정 파일, 패키지 파일, 이미지 파일이 섞여 있을 때는 어떤 파일이 커밋에 들어가는지 명확히 알아야 합니다.

변경 일부만 커밋하고 싶다면 다음 명령도 유용합니다.

git add -p

-p는 변경 덩어리별로 포함 여부를 묻습니다. 같은 파일 안에서도 문서 수정과 디버그 로그 제거를 나눠 커밋할 수 있어 실무에서 자주 사용합니다.

4. 커밋 메시지는 결과보다 이유를 적는다

커밋은 변경 이력의 한 줄 요약입니다. 나중에 문제가 생겼을 때 “왜 이 변경이 들어갔는가”를 파악하는 단서가 됩니다. 좋은 커밋 메시지는 짧지만 구체적입니다.

git commit -m "docs: add GitHub push beginner guide"
git commit -m "fix: prevent empty related posts from rendering"
git commit -m "chore: update Astro content schema"

한국어로 작성해도 됩니다.

git commit -m "docs: Git 커밋과 푸시 가이드 추가"

팀에서는 feat, fix, docs, chore, refactor, test 같은 Conventional Commits 형식을 자주 사용합니다. 꼭 규칙을 외우기보다 “문서 추가인지, 버그 수정인지, 기능 추가인지”가 드러나게 쓰는 것이 핵심입니다.

나쁜 메시지의 예는 update, fix, 작업, 수정함처럼 무엇을 바꿨는지 알 수 없는 표현입니다. 지금은 빨리 넘어가도 3개월 뒤에는 본인도 기억하지 못합니다.

5. 푸시는 원격 저장소에 업로드하는 단계다

커밋은 내 컴퓨터의 로컬 저장소에 기록됩니다. GitHub에 보이게 하려면 푸시해야 합니다.

git push

처음 만든 브랜치라면 원격 브랜치 연결이 필요할 수 있습니다.

git push -u origin my-branch

origin은 보통 GitHub 원격 저장소의 별칭이고, my-branch는 현재 브랜치 이름입니다. -u를 한 번 설정하면 다음부터는 git push만 실행해도 같은 원격 브랜치로 올라갑니다.

푸시가 거절될 때는 다른 사람이 먼저 원격에 커밋을 올렸거나, 권한이 없거나, 보호된 브랜치에 직접 푸시하려 했을 가능성이 있습니다. 메시지를 읽지 않고 --force를 붙이는 것은 위험합니다. 강제 푸시는 다른 사람의 작업 이력을 덮을 수 있으므로 팀 규칙을 모르면 사용하지 마세요.

6. 커밋 전 실무 체크리스트

커밋하기 전에는 다음 항목을 확인합니다.

• git status에서 의도한 파일만 보이는가
• git diff에 API 키, 토큰, 비밀번호, 개인정보가 없는가
• 임시 console.log, 테스트용 주석, 로컬 경로가 남아 있지 않은가
• 이미지나 빌드 결과물이 불필요하게 포함되지 않았는가
• 변경 단위가 한 가지 목적에 집중되어 있는가
• 관련 문서나 내부 링크가 깨지지 않는가
• 가능한 경우 빌드나 테스트를 실행했는가

블로그 글만 수정하더라도 YAML frontmatter 오타 하나로 빌드가 실패할 수 있습니다. title, description, pubDate, tags처럼 스키마가 정한 필드가 있으면 빠짐없이 넣어야 합니다.

7. 자주 하는 실수와 대응

실수 1: 파일을 잘못 추가했다

아직 커밋 전이라면 스테이지에서만 내리면 됩니다.

git restore --staged path/to/file

파일 내용은 유지되고 커밋 대상에서만 빠집니다. 초보자가 가장 안전하게 쓸 수 있는 복구 명령 중 하나입니다.

실수 2: 커밋 메시지를 잘못 썼다

아직 푸시하지 않은 마지막 커밋이라면 메시지를 고칠 수 있습니다.

git commit --amend -m "docs: add clearer Git push guide"

다만 이미 팀과 공유한 커밋을 바꾸면 이력이 달라질 수 있으므로, 협업 중이라면 새 커밋으로 수정하는 편이 안전합니다.

실수 3: 민감 정보를 커밋했다

가장 먼저 해야 할 일은 해당 키를 폐기하고 새로 발급하는 것입니다. Git 이력에서 지우는 작업보다 키 회전이 먼저입니다. 이미 원격에 푸시했다면 단순히 파일에서 삭제하는 것만으로는 부족합니다. 키가 노출되었다고 보고 비밀번호 변경, 토큰 재발급, 접근 로그 확인을 진행하세요.

실수 4: 원격 변경과 충돌했다

다른 사람이 같은 파일을 고쳤다면 충돌이 발생합니다.

git pull

충돌 표시가 난 파일을 열어 필요한 내용을 정리하고, 다시 git add, git commit을 진행합니다. 충돌 해결은 처음엔 부담스럽지만, 실제로는 “두 변경 중 무엇을 남길지”를 결정하는 과정입니다.

8. 브랜치를 나눠 작업하면 안전하다

작은 개인 블로그라도 main에 직접 작업하기보다 기능별 브랜치를 만들면 실수를 줄일 수 있습니다.

git switch -c docs/git-guide

브랜치 이름은 작업 목적이 보이게 만듭니다. 예를 들어 docs/security-posts, fix/post-card-date, feat/search-page처럼 정리하면 GitHub에서도 의미를 파악하기 쉽습니다. 작업이 끝나면 푸시하고 Pull Request를 만들어 검토한 뒤 병합합니다.

9. 기본 흐름 요약

처음 Git을 배울 때는 아래 흐름을 반복하면 됩니다.

git status
git diff
git add path/to/file
git status
git commit -m "docs: add new blog post"
git push

중요한 것은 명령어를 외우는 것이 아니라 각 단계의 의미를 이해하는 것입니다. status는 현재 상태 확인, diff는 내용 검토, add는 커밋 대상 선택, commit은 로컬 기록, push는 원격 업로드입니다.

Git은 실수를 하지 않게 해 주는 도구가 아니라 실수를 추적하고 되돌릴 수 있게 해 주는 도구입니다. 그래서 커밋을 작고 명확하게 남길수록 나중에 문제를 찾기 쉬워집니다. 오늘부터는 “작업 끝나면 한번에 올리기”보다 “의미 있는 단위로 확인하고 기록하기”를 목표로 해 보세요.