🔀 Git 브랜치 전략 & 명령어 매뉴얼

실무에서 바로 쓰는 흐름대로, 개념→명령어→주의점→복구까지 한 번에 정리했습니다.

---

목차

1. 시작 준비 – 사용자 정보, 편집기, 줄바꿈
2. 저장소와 원격 – clone, remote, fetch vs pull, tracking
3. 브랜치 만들기/이동 – 안전한 파생 규칙
4. 하루 업무 흐름(권장 루틴) – 번호 순서 전체 명령어
5. Merge vs Rebase – 개념/그림/언제/주의점/명령어
6. 내 브랜치를 최신화하는 3가지 방법(merge/rebase/새로파생)
7. 충돌 처리 가이드 – 병합/리베이스/중단·재시도
8. Stash(임시저장) – 실무에서 쓰는 모든 패턴
9. 커밋 관리 – Conventional Commits, amend, squash/fixup
10. 되돌리기 & 복구 – revert/reset/restore/reflog/force-with-lease
11. .gitignore 제대로 – 이미 추적된 파일 제외하기
12. PR(코드 리뷰) 흐름 – push, 리뷰, 머지 전략
13. 자주 겪는 오류/상황별 처방전 – 당신의 콘솔 메시지 해결집
14. 치트시트(작업→명령어 매핑 표)

---

1) 시작 준비 – 사용자 정보, 편집기, 줄바꿈

• 사용자/메일(커밋 서명자)

git config --global user.name "홍길동"
git config --global user.email "me@example.com"

• 기본 편집기(옵션)

git config --global core.editor "code --wait"      # VS Code

• 줄바꿈(팀 규칙에 맞게)

git config --global core.autocrlf input            # macOS/Linux 권장
git config --global core.autocrlf true             # Windows 혼자 개발 시

• 상태/최근 기록/원격 확인

git status
git log --oneline --graph --decorate -20
git remote -v

---

2) 저장소와 원격 – clone, remote, fetch vs pull, tracking

• 클론

git clone <url>
cd <repo>

• 원격/브랜치 추적(Tracking)

git branch -vv                    # 현재 브랜치가 어떤 원격 브랜치를 추적하는지
git push -u origin feature/x      # 최초 푸시 시 -u로 추적 설정

• fetch vs pull

  • fetch: “원격 정보만 갱신(병합/리베이스 X)”
  • pull: “fetch + 현재 브랜치에 반영(merge 또는 rebase)”

git fetch origin
git pull --ff-only                 # 실수로 merge commit 생기는 것 방지
# 또는
git pull --rebase --autostash      # 개인 브랜치에서 깔끔히 최신화할 때

---

3) 브랜치 만들기/이동 – 안전한 파생 규칙

• 최신 development에서 바로 파생(권장)

git fetch origin
git switch development
git pull --ff-only origin development
git switch -c feature/login       # development 최신 커밋에서 새 브랜치

• 기존 브랜치로 이동(구문 2종)

git switch feature/login
# (구식) git checkout feature/login

• 브랜치 네이밍(권장)

  • feature/기능-설명
  • bugfix/이슈-설명
  • hotfix/긴급-설명

---

4) 하루 업무 흐름(권장 루틴)

1. 원격 최신 확인

git fetch origin
git switch development
git pull --ff-only origin development

2. 기능 브랜치 생성/이동

git switch -c feature/awesome
# (이미 만든 경우) git switch feature/awesome

3. 작업 → 상태 확인 → 스테이징 → 커밋

git status
git add -A
git commit -m "feat(awesome): 초기 컴포넌트 추가"

4. 중간중간 최신화 반영(아래 6장 참고: merge 또는 rebase)
5. 원격에 푸시(+추적 설정)

git push -u origin feature/awesome

6. PR 생성 → 리뷰 반영 → 스쿼시/머지 전략 선택(12장 참고)

---

5) Merge vs Rebase – 핵심 비교

개념 그림

development: A -- B -- C -- D

feature/app: E -- F

Merge(머지)

git switch feature/app
git merge development

결과(merge commit M 생성)
A -- B -- C -- D ----------- M
\ /
E--F

• 장점: 안전, 공동 작업에 적합, 원본 히스토리 보존
• 단점: 머지 커밋이 누적되면 그래프가 복잡

옵션:

git merge --no-ff --no-edit development   # merge commit을 항상 남김

Rebase(리베이스)

git switch feature/app
git rebase development

결과(직선형)
A -- B -- C -- D -- E' -- F'

• 장점: 히스토리 깔끔(읽기 쉬움)
• 단점: 공유 브랜치에서 금지(히스토리 재작성); 충돌을 커밋마다 해결

리베이스 중 유용한 명령:

git rebase --continue
git rebase --skip
git rebase --abort

언제 무엇을?

• 팀 공용 브랜치(main/development): Merge 권장
• 개인 작업 브랜치(PR 전 정리): Rebase 자주 사용
• 원격에 이미 공유된 브랜치를 rebase → 위험. 꼭 필요하면 협의 후 --force-with-lease

한눈 비교

항목	merge	rebase
히스토리	분기+머지 커밋 남김	직선화(깔끔)
안전성	높음(공유에 적합)	낮음(공유 금지)
충돌 처리	한 번에	커밋마다
사용 맥락	팀/공유	개인/PR 전

---

6) 내 브랜치를 최신화하는 3가지 방법

전제: 항상 먼저 development를 최신으로

git fetch origin
git switch development
git pull --ff-only origin development

방법 A) 내 브랜치에서 development를 머지(안전, 권장)

git switch feature/awesome
git merge development
# 충돌 시 해결 → git add -A → git commit

방법 B) 내 브랜치를 development 위로 리베이스(히스토리 깔끔)

git switch feature/awesome
git rebase development
# 충돌 시 해결 → git add -A → git rebase --continue

방법 C) 아예 최신 development에서 새로 파생(히스토리 가장 깔끔)

git switch development
git pull --ff-only origin development
git switch -c feature/awesome-v2
# 필요 커밋만 cherry-pick
git cherry-pick <E> <F> ...

이미 만들어둔 브랜치에 development 최신을 합칠 때”는

git checkout {new\_branch} && git merge development

명령어 사용 가능. 단, 항상 그 전에 development를 원격과 동기화해야 함.

---

7) 충돌 처리 가이드

공통

• 충돌 파일에 <<<<<<<, =======, >>>>>>> 마커 등장
• 원하는 코드로 정리 후 저장
• 스테이징하여 다음 단계 진행

머지 중

git merge development
# 충돌 해결
git add -A
git commit
# 중단하려면: git merge --abort

리베이스 중

git rebase development
# 충돌 해결
git add -A
git rebase --continue
# 전체 중단: git rebase --abort

팁

• 파일별로 순차 해결: git add <file> 반복
• 충돌 보기: git status, git diff, 에디터 내 Conflict View 활용
• 테스트/빌드 통과 확인 후 커밋

---

8) Stash(임시저장) – 실무 패턴

기본

git stash                 # 추적 파일 변경만
git stash -u              # untracked(새 파일)도 포함
git stash -a              # .gitignore까지 포함(주의)
git stash list
git stash show -p stash@{0}
git stash apply stash@{0} # 적용(스택에 남김)
git stash pop             # 적용+스택에서 제거

부분 적용(대화형)

git stash -p

인덱스 유지/메시지

git stash --keep-index
git stash push -m "WIP: 로그인 폼"

---

9) 커밋 관리 – 좋은 메시지와 정리

Conventional Commits(추천)

• 타입: feat, fix, docs, style, refactor, test, chore, build, ci, perf
• 형식: type(scope): 메시지
• 예:

feat(auth): 로그인 폼 및 유효성 검증 추가
fix(api): 400 응답 시 에러코드 파싱 버그 수정
docs(readme): 설치 방법 갱신

커밋 수정

git commit --amend                 # 직전 커밋 메시지/내용 수정

히스토리 정리(인터랙티브 리베이스)

git rebase -i HEAD~5
# pick → squash/fixup 로 묶기
# autosquash
git commit --fixup <commit>
git rebase -i --autosquash HEAD~5

---

10) 되돌리기 & 복구

안전하게 되돌리기(공유 브랜치 OK)

git revert <commit>                # 반대 변경 커밋 생성

히스토리 자체를 이동(공유 브랜치 X)

git reset --soft <commit>          # 인덱스/워크트리 유지
git reset --mixed <commit>         # 기본, 인덱스 해제
git reset --hard <commit>          # 전부 되돌림(주의)

파일 단위 복원(새 Git)

git restore <path>                 # 워크트리만 복원
git restore --staged <path>        # 스테이징 해제

마지막 안전망 – reflog

git reflog                         # 브랜치 이동/리셋/리베이스 이력
git reset --hard <reflog-id>       # 과거 지점으로 복원

원격 덮어쓰기(꼭 필요할 때만)

git push --force-with-lease        # 내 변경만 덮도록 안전장치

---

11) .gitignore 제대로 – 이미 추적된 파일 제외

1. .gitignore에 패턴 추가
2. 인덱스에서만 제거(파일은 남김)

git rm --cached -r path/or/file
git commit -m "chore: ignore 빌드 산출물"
git push

전역 ignore(개인 환경 파일)

git config --global core.excludesfile ~/.gitignore_global

---

12) PR(코드 리뷰) 흐름

1. 기능 브랜치 푸시

git push -u origin feature/awesome

2. PR 생성(베이스: development 또는 main)

3. 리뷰 반영 → 추가 커밋 푸시

4. 병합 전략

   • Squash Merge: PR 커밋들을 1개로. 히스토리 깨끗
   • Merge Commit: 머지 커밋 남김. 기록 충실
   • Rebase & Merge: 직선화하되, 공유 정책에 맞춰 신중히

5. 머지 후 브랜치 정리

git branch -d feature/awesome
git push origin --delete feature/awesome

---

13) 자주 겪는 오류/상황별 처방전

A) “Your local changes would be overwritten by checkout”

• 원인: 미커밋 변경이 있어서 브랜치 전환 불가
• 해결:

git add -A && git commit -m "wip: 저장"
# 또는
git stash
git switch 다른브랜치
# 또는 특정 파일만 임시 백업/삭제

B) “The following untracked working tree files would be overwritten by checkout”

• 원인: 전환하려는 브랜치에 동일 경로 파일 존재(내 쪽은 untracked)
• 해결(선택)

git add -A && git commit   # 커밋 후 전환
git stash -u               # untracked 포함 임시저장
git clean -fd              # 진짜 삭제(주의)

C) .gitignore 추가했는데 여전히 올라감

git rm --cached -r path/
git commit -m "chore: stop tracking generated files"
git push

D) development가 “Already up to date”인데 최신이 아님

git fetch origin
git switch development
git reset --hard origin/development   # 원격 기준으로 딱 맞춤(주의)

E) 리베이스 꼬였을 때

git rebase --abort
# 또는
git reflog  # 이전 상태 찾아 복구
git reset --hard <reflog-id>

F) 잘못 푸시한 커밋 되돌리기(공유 브랜치)

git revert <commit>
git push

G) 과거 실수로 민감정보 푸시(비밀번호/키)

• 즉시 키 폐기/교체 → 새 키 발급
• 기록 정리(BFG Repo-Cleaner 등) + 정책 공지

---

14) 치트시트(작업→명령어)

브랜치 최신화(개인 브랜치에서 안전)

• merge:
  git switch feature/x
  git merge development

• rebase:
  git switch feature/x
  git rebase development

새 브랜치 시작(항상 최신 development에서)

• git fetch origin
• git switch development
• git pull --ff-only origin development
• git switch -c feature/x

PR 전 커밋 정리

• git rebase -i HEAD~N
• pick → squash/fixup
• git push --force-with-lease

되돌리기(공유 안전)

• git revert

이미 추적 중인 파일 ignore

• .gitignore 추가
• git rm --cached -r path/
• git commit && git push

브랜치 전환 오류 해결

• git add -A && git commit
• git stash (-u)
• git clean -fd (주의)

마지막 복구망

• git reflog
• git reset --hard

---

저는 이런 방식으로 작업을 진행하고 있습니다.

1. 최신 베이스에서 브랜치 파생
2. 작은 단위로 커밋(명확 메시지)
3. 주기적 최신화(merge 또는 rebase 원칙 유지)
4. PR로 검토·병합