Git 사용 가이드 — 기초부터 실전 워크플로우까지

Git이 필요한 이유

코드를 수정하다 실수하면 되돌릴 수 있어야 합니다. 여러 사람이 같은 코드를 동시에 수정할 수 있어야 합니다. Git은 이 두 가지를 해결하는 분산 버전 관리 시스템입니다.

Git의 핵심 특징:

로컬에서 독립 작업 — 네트워크 없이도 커밋, 브랜치, 히스토리 조회 가능
브랜치가 가볍다 — 새 브랜치 생성이 거의 즉각적 (포인터 하나 생성)
변경 이력 추적 — 누가, 언제, 왜 수정했는지 모두 기록

초기 설정

Git을 설치한 후 가장 먼저 해야 할 설정입니다.

# 사용자 정보 설정 (커밋에 기록됨)
git config --global user.name "홍길동"
git config --global user.email "hong@example.com"

# 기본 브랜치 이름을 main으로 설정
git config --global init.defaultBranch main

# 설정 확인
git config --list
# user.name=홍길동
# user.email=hong@example.com
# init.defaultbranch=main

핵심 개념: 3가지 영역

Git에는 파일이 거치는 3가지 영역이 있습니다.

영역	설명	비유
Working Directory	실제 파일을 편집하는 곳	작업 책상
Staging Area (Index)	다음 커밋에 포함할 변경을 모아두는 곳	택배 포장 구역
Repository (.git)	커밋된 스냅샷이 저장되는 곳	창고

흐름: 작업 → git add → Staging → git commit → Repository

필수 명령어

저장소 생성과 클론

# 새 저장소 초기화
mkdir my-project && cd my-project
git init
# Initialized empty Git repository in /my-project/.git/

# 기존 원격 저장소 클론
git clone https://github.com/user/repo.git
git clone https://github.com/user/repo.git my-folder   # 폴더명 지정

상태 확인과 변경 추적

# 현재 상태 확인 (가장 자주 쓰는 명령어)
git status
# On branch main
# Changes not staged for commit:
#   modified:   src/app.js
# Untracked files:
#   src/utils.js

# 변경 내용 비교
git diff                   # Working → Staging 비교
git diff --staged          # Staging → 마지막 커밋 비교

# 커밋 히스토리 조회
git log --oneline --graph
# * a1b2c3d (HEAD -> main) feat: 로그인 기능 추가
# * d4e5f6g fix: 버그 수정
# * g7h8i9j init: 프로젝트 초기화

스테이징과 커밋

# 특정 파일 스테이징
git add src/app.js

# 변경된 파일 전부 스테이징 (신규 파일 포함)
git add .

# 커밋 (메시지는 "왜" 변경했는지 기록)
git commit -m "feat: 사용자 로그인 기능 추가"

# 스테이징 + 커밋 한 번에 (추적 중인 파일만)
git commit -am "fix: 비밀번호 검증 오류 수정"

커밋 메시지 컨벤션

팀에서 통일된 형식을 사용하면 히스토리 파악이 쉬워집니다.

접두어	용도	예시
feat	새 기능	`feat: 소셜 로그인 추가`
fix	버그 수정	`fix: 세션 만료 오류 해결`
refactor	리팩토링 (동작 변경 없음)	`refactor: 인증 모듈 분리`
docs	문서 변경	`docs: API 엔드포인트 설명 추가`
test	테스트 추가/수정	`test: 로그인 실패 케이스 추가`
chore	빌드, 설정 변경	`chore: ESLint 규칙 업데이트`
perf	성능 개선	`perf: 쿼리 인덱스 최적화`

브랜치 사용법

브랜치는 독립된 작업 공간입니다. main 브랜치를 안전하게 유지하면서 기능을 개발합니다.

# 브랜치 목록 확인
git branch
# * main
#   feature/login

# 브랜치 생성 + 전환
git checkout -b feature/login
# 또는 (Git 2.23+)
git switch -c feature/login

# 브랜치 전환
git checkout main
git switch main

# 브랜치 삭제 (병합 완료 후)
git branch -d feature/login

병합 (Merge)

# main에 feature 브랜치 병합
git checkout main
git merge feature/login
# 충돌 없으면 자동 병합 완료

# 충돌 발생 시
# 1. 충돌 파일 수동 편집
# 2. 충돌 해결 후 스테이징
git add src/auth.js
# 3. 병합 커밋 생성
git commit -m "merge: feature/login 병합"

Rebase vs Merge

항목	Merge	Rebase
히스토리	병합 커밋이 남음 (분기 보임)	일직선 히스토리 (깔끔)
안전성	원본 히스토리 보존	커밋 해시가 변경됨
사용 시점	main에 병합할 때	feature 브랜치를 main에 맞출 때
규칙	공유 브랜치에 안전	공유 브랜치에 rebase 금지

# feature 브랜치에서 main의 최신 변경을 가져올 때
git checkout feature/login
git rebase main
# → feature의 커밋이 main 최신 위에 다시 쌓임

원격 저장소 (Remote)

GitHub, GitLab 등 원격 저장소와의 동기화 명령어입니다.

# 원격 저장소 등록
git remote add origin https://github.com/user/repo.git

# 원격 목록 확인
git remote -v

# 푸시 (로컬 → 원격)
git push origin main
git push -u origin feature/login    # -u: 업스트림 설정 (이후 git push만으로 충분)

# 풀 (원격 → 로컬, fetch + merge)
git pull origin main

# 원격 변경만 가져오기 (병합 없이)
git fetch origin

실수 되돌리기

상황	명령어	설명
스테이징 취소	`git restore --staged file.js`	add 취소 (파일 내용 유지)
작업 내용 되돌리기	`git restore file.js`	마지막 커밋 상태로 복원 (주의: 변경 삭제)
마지막 커밋 수정	`git commit --amend`	메시지 수정 또는 파일 추가 (미푸시 커밋만)
특정 커밋 되돌리기	`git revert a1b2c3d`	되돌리는 새 커밋 생성 (안전)
커밋 히스토리 초기화	`git reset --soft HEAD~1`	커밋 취소, 변경은 Staging에 보존

# 가장 흔한 실수: 파일 빼먹고 커밋
git add forgotten-file.js
git commit --amend --no-edit    # 메시지 유지하면서 파일 추가

# 위험한 명령어 — 신중하게 사용
git reset --hard HEAD~1    # 커밋 + 변경 모두 삭제 (복구 어려움)

실전 협업 워크플로우

팀에서 가장 많이 사용하는 GitHub Flow 기반 워크플로우입니다.

# 1. main에서 최신 코드 받기
git checkout main
git pull origin main

# 2. 기능 브랜치 생성
git checkout -b feature/user-profile

# 3. 작업 + 커밋 (여러 번 반복)
git add .
git commit -m "feat: 프로필 편집 UI 구현"
git commit -m "feat: 프로필 이미지 업로드 추가"

# 4. 원격에 푸시
git push -u origin feature/user-profile

# 5. GitHub에서 Pull Request 생성
# → 코드 리뷰 → 승인 → main에 병합

# 6. 로컬 정리
git checkout main
git pull origin main
git branch -d feature/user-profile

.gitignore 설정

버전 관리에서 제외할 파일을 지정합니다. 프로젝트 루트에 .gitignore 파일을 만드세요.

# 의존성
node_modules/
vendor/
venv/

# 빌드 결과물
dist/
build/
*.pyc

# 환경변수/시크릿
.env
.env.local
*.pem

# IDE 설정
.vscode/
.idea/
*.swp

# OS 파일
.DS_Store
Thumbs.db

정리

상황	명령어
프로젝트 시작	`git init` 또는 `git clone`
변경 저장	`git add .` → `git commit -m "메시지"`
상태 확인	`git status`, `git log --oneline`
브랜치 작업	`git switch -c feature/xxx` → 작업 → `git merge`
원격 동기화	`git pull` → 작업 → `git push`
실수 되돌리기	`git restore`, `git revert`, `git reset --soft`

Git은 도구이지 목적이 아닙니다. 복잡한 명령어를 외우려 하지 말고, 위 테이블의 기본 흐름만 익히면 대부분의 상황을 처리할 수 있습니다. 나머지는 필요할 때 찾아보세요.