| name | git |
| description | Git 버전 관리 모범 관례 및 워크플로우 가이드. 다음 상황에서 사용: (1) Git 커밋 메시지 작성 시 (Conventional Commits 규칙 적용), (2) 브랜치 생성 및 관리 시 (GitHub Flow 기반), (3) PR 생성 및 병합 전략 선택 시, (4) Git 히스토리 정리 작업 시 (rebase, squash, cherry-pick), (5) Merge conflict 해결 시, (6) 'git', '.git', 'commit', 'branch', 'merge', 'rebase' 키워드가 포함된 작업 시 |
| license | MIT |
| metadata | {"author":"DaleStudy","version":"1.0.0"} |
| allowed-tools | Bash(git:*) |
Git
Git 버전 관리 모범 관례 및 워크플로우 가이드.
커밋 메시지 컨벤션
Conventional Commits 사용
커밋 메시지는 <type>: <description> 형식을 따른다:
feat: add form validation to login page
fix: prevent duplicate email check error on signup
docs: add installation guide to README
refactor: extract auth logic into separate module
test: add payment feature tests
chore: update dependencies
주요 타입
| 타입 | 설명 | 예시 |
|---|
feat | 새로운 기능 추가 | feat: add dark mode support |
fix | 버그 수정 | fix: prevent token deletion on logout |
docs | 문서 변경 (코드 변경 없음) | docs: update API documentation |
style | 코드 포맷팅, 세미콜론 누락 (동작 변경 X) | style: apply ESLint rules |
refactor | 리팩토링 (기능 변경 없음) | refactor: extract utility functions |
test | 테스트 코드 추가/수정 | test: add login API tests |
chore | 빌드, 설정 변경 (src 변경 없음) | chore: update Webpack config |
perf | 성능 개선 | perf: implement lazy loading for images |
상세 형식 (선택사항)
<type>(<scope>): <subject>
<body>
<footer>
예시:
feat(auth): implement JWT-based authentication
- Issue access and refresh tokens
- Store refresh tokens in Redis
- Add token renewal API endpoint
Closes #123
자주 하는 실수
git commit -m "bug fix"
git commit -m "fix: fix issue"
git commit -m "feat: implement login, signup, and password reset"
git commit -m "feat: add form validation to login page"
커밋 메시지 작성 가이드라인
- 첫 줄은 50자 이내 - 간결한 요약
- 현재형 사용 - "added" (X) → "add" (O)
- 명령형 어조 - "adds" (X) → "add" (O)
- 첫 글자 소문자 -
Feat: (X) → feat: (O)
- 마침표 금지 -
feat: add feature. (X) → feat: add feature (O)
- 본문은 72자마다 줄바꿈 - 가독성 향상
- Why > What - 변경한 내용보다 변경한 이유를 설명
- 영어로 작성 - 릴리즈 노트 생성 도구와의 호환성을 위해
GitHub Flow 워크플로우
브랜치 전략
main (항상 배포 가능한 상태)
├── feature/login-form
├── fix/payment-error
└── refactor/user-service
기본 브랜치
새 저장소 생성 시 기본 브랜치는 main을 사용한다 (과거의 master 대신):
git init -b main
git branch -m master main
git push -u origin main
git config --global init.defaultBranch main
참고: GitHub, GitLab, Bitbucket 등 대부분의 Git 호스팅 서비스는 2020년부터 기본 브랜치를 main으로 사용한다.
브랜치 네이밍
feature/user-authentication
fix/header-layout-bug
refactor/payment-module
docs/api-documentation
test/user-service
chore/update-dependencies
작업 흐름
git switch main
git pull origin main
git switch -c feature/dark-mode
git add .
git commit -m "feat: add dark mode toggle button"
git push origin feature/dark-mode
gh pr create --title "feat: add dark mode support" --body "..."
gh pr merge <PR번호> --squash
git switch main
git pull origin main
git branch -d feature/dark-mode
PR 병합 전략
| 전략 | 설명 | 언제 사용 |
|---|
| Squash | 모든 커밋을 하나로 합침 | 기능 브랜치 (권장) |
| Merge | 병합 커밋 생성, 히스토리 보존 | 릴리스 브랜치 |
| Rebase | 선형 히스토리 유지, 병합 커밋 X | 간단한 변경, 깔끔한 히스토리 |
gh pr merge 123 --squash
gh pr merge 123 --merge
gh pr merge 123 --rebase
Git 히스토리 관리
Rebase
Interactive Rebase (커밋 정리)
git rebase -i HEAD~3
예시:
pick a1b2c3d feat: implement login feature
pick d4e5f6g fix: typo in variable name
pick g7h8i9j fix: rename variable for clarity
pick a1b2c3d feat: implement login feature
fixup d4e5f6g fix: typo in variable name
fixup g7h8i9j fix: rename variable for clarity
Rebase onto main (브랜치 최신화)
git switch main
git pull origin main
git switch feature/my-feature
git rebase main
git add .
git rebase --continue
git rebase --abort
Cherry-pick (특정 커밋만 가져오기)
git cherry-pick <commit-hash>
git cherry-pick <commit-hash1> <commit-hash2>
git add .
git cherry-pick --continue
Commit Amend (마지막 커밋 수정)
git commit --amend -m "fix: correct commit message"
git add forgotten-file.ts
git commit --amend --no-edit
Reset vs Revert
git reset --soft HEAD~1
git reset --mixed HEAD~1
git reset --hard HEAD~1
git revert <commit-hash>
git revert HEAD
Merge Conflict 해결
Conflict 발생 시나리오
git merge main
git rebase main
Conflict 해결 과정
git status
git add src/index.ts
git merge --continue
git rebase --continue
Conflict 해결 전략
git restore --ours <file>
git restore --theirs <file>
git merge --abort
git rebase --abort
자주 사용하는 명령어
브랜치 작업 (git switch)
git switch main
git switch feature/my-feature
git switch -c feature/new-feature
git switch -
git switch -c local-branch origin/remote-branch
참고: Git 2.23+ (2019년 8월)부터 git switch를 사용한다. 기존 git checkout은 브랜치 전환, 파일 복원 등 여러 역할을 담당해 혼란을 야기했다. git switch는 브랜치 전환만 담당한다.
파일 복원 (git restore)
git restore <file>
git restore --staged <file>
git restore --staged --worktree <file>
git restore --source=<commit-hash> <file>
참고: git restore는 파일 복원 전용 명령어다. 기존 git checkout -- <file>을 대체한다.
상태 확인
git status
git log --oneline
git log --graph
git diff
git diff --staged
git show <commit-hash>
Stash (임시 저장)
git stash
git stash list
git stash pop
git stash apply
git stash drop
git stash clear
원격 저장소
git remote -v
git fetch origin
git pull origin main
git push origin main
git push -f origin main
주의 사항 (Anti-patterns)
현재 디렉토리에서 불필요한 git -C 사용
git -C /path/to/current/repo log --oneline
git log --oneline
현재 디렉토리가 작업 대상 레포지토리와 동일하면 git -C 옵션은 불필요한 중복이다. 다른 경로의 레포지토리를 대상으로 할 때만 사용한다.
보안 및 주의사항
절대 커밋하면 안 되는 파일
.env
.env.local
*.key
*.pem
secrets/
node_modules/
dist/
.DS_Store
실수로 커밋한 시크릿 제거
brew install bfg
bfg --delete-files .env
git reflog expire --expire=now --all && git gc --prune=now --aggressive
Force Push 금지 (공유 브랜치)
git push -f origin main
git push -f origin feature/my-branch
GitHub CLI 활용
gh pr create --title "feat: add new feature" --body "Description..."
gh pr list
gh pr view 123
gh pr checkout 123
gh pr merge 123 --squash
gh issue create --title "Bug found" --body "Description..."
추가 학습 자료
