Git 버전 관리 모범 관례 및 워크플로우 가이드.
Conventional Commits 사용
使用Conventional Commits
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: 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: add dark mode support
|
| 버그 수정 | fix: prevent token deletion on logout
|
| 문서 변경 (코드 변경 없음) | docs: update API documentation
|
| 코드 포맷팅, 세미콜론 누락 (동작 변경 X) | style: apply ESLint rules
|
| 리팩토링 (기능 변경 없음) | refactor: extract utility functions
|
| 테스트 코드 추가/수정 | test: add login API tests
|
| 빌드, 설정 변경 (src 변경 없음) | chore: update Webpack config
|
| 성능 개선 | perf: implement lazy loading for images
|
| 类型 | 说明 | 示例 |
|---|
| 添加新功能 | feat: add dark mode support
|
| 修复Bug | fix: prevent token deletion on logout
|
| 修改文档（无代码变更） | docs: update API documentation
|
| 代码格式化、补充分号等（无功能变更） | style: apply ESLint rules
|
| 代码重构（无功能变更） | refactor: extract utility functions
|
| 添加/修改测试代码 | test: add login API tests
|
| 构建、配置变更（无源码变更） | chore: update Webpack config
|
| 性能优化 | 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
<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 "fix: fix issue"
git commit -m "fix: fix issue"
❌ 한 커밋에 여러 작업
❌ 单个提交包含多项操作
git commit -m "feat: implement login, signup, and password reset"
git commit -m "feat: implement login, signup, and password reset"
git commit -m "feat: add form validation to login page"
git commit -m "feat: add form validation to login page"
- 첫 줄은 50자 이내 - 간결한 요약
- 현재형 사용 - "added" (X) → "add" (O)
- 명령형 어조 - "adds" (X) → "add" (O)
- 첫 글자 소문자 - (X) → (O)
- 마침표 금지 - (X) → (O)
- 본문은 72자마다 줄바꿈 - 가독성 향상
- Why > What - 변경한 내용보다 변경한 이유를 설명
- 영어로 작성 - 릴리즈 노트 생성 도구와의 호환성을 위해
- 首行不超过50字符 - 简洁总结
- 使用现在时 - "added"（错误）→ "add"（正确）
- 使用命令式语气 - "adds"（错误）→ "add"（正确）
- 首字母小写 - （错误）→ （正确）
- 末尾不加句号 - （错误）→ （正确）
- 正文每72字符换行 - 提升可读性
- 原因 > 内容 - 优先说明变更原因而非变更内容
- 使用英文编写 - 确保与发布笔记生成工具兼容
GitHub Flow 워크플로우
GitHub Flow工作流
main (항상 배포 가능한 상태)
├── feature/login-form
├── fix/payment-error
└── refactor/user-service
main (始终处于可发布状态)
├── feature/login-form
├── fix/payment-error
└── refactor/user-service
새 저장소 생성 시 기본 브랜치는
을 사용한다 (과거의
대신):
새 저장소 초기화 시 main 브랜치로 시작
初始化新仓库时以main分支启动
또는 기존 저장소에서 기본 브랜치 변경
或修改现有仓库的默认分支
git branch -m master main
git push -u origin main
git branch -m master main
git push -u origin main
Git 전역 설정 (모든 새 저장소에 적용)
Git全局配置（应用于所有新仓库）
git config --global init.defaultBranch main
**참고**: GitHub, GitLab, Bitbucket 등 대부분의 Git 호스팅 서비스는 2020년부터 기본 브랜치를 `main`으로 사용한다.
git config --global init.defaultBranch main
**参考**：GitHub、GitLab、Bitbucket等主流Git托管服务从2020年起默认使用`main`作为默认分支。
형식: <type>/<description>
格式: <type>/<description>
feature/user-authentication
fix/header-layout-bug
refactor/payment-module
docs/api-documentation
test/user-service
chore/update-dependencies
feature/user-authentication
fix/header-layout-bug
refactor/payment-module
docs/api-documentation
test/user-service
chore/update-dependencies
1. main에서 최신 상태 받기
1. 获取main分支的最新状态
git switch main
git pull origin main
git switch main
git pull origin main
git switch -c feature/dark-mode
git switch -c feature/dark-mode
git add .
git commit -m "feat: add dark mode toggle button"
git add .
git commit -m "feat: add dark mode toggle button"
git push origin feature/dark-mode
git push origin feature/dark-mode
5. GitHub에서 PR 생성
5. 在GitHub上创建PR
gh pr create --title "feat: add dark mode support" --body "..."
gh pr create --title "feat: add dark mode support" --body "..."
6. 코드 리뷰 후 main에 병합 (GitHub UI 또는 CLI)
6. 代码评审后合并到main分支（通过GitHub界面或CLI）
gh pr merge <PR번호> --squash # 또는 --merge, --rebase
gh pr merge <PR编号> --squash # 或--merge、--rebase
7. 로컬 main 업데이트 및 브랜치 삭제
7. 更新本地main分支并删除旧分支
git switch main
git pull origin main
git branch -d feature/dark-mode
git switch main
git pull origin main
git branch -d feature/dark-mode
| 전략 | 설명 | 언제 사용 |
|---|
| Squash | 모든 커밋을 하나로 합침 | 기능 브랜치 (권장) |
| Merge | 병합 커밋 생성, 히스토리 보존 | 릴리스 브랜치 |
| Rebase | 선형 히스토리 유지, 병합 커밋 X | 간단한 변경, 깔끔한 히스토리 |
| 策略 | 说明 | 使用场景 |
|---|
| Squash | 将所有提交合并为一个 | 功能分支（推荐） |
| Merge | 生成合并提交，保留历史记录 | 发布分支 |
| Rebase | 维持线性历史，无合并提交 | 简单变更、需要整洁历史时 |
Squash (권장 - 기능 단위로 커밋 정리)
Squash（推荐 - 按功能单元整理提交）
Merge (히스토리 보존)
Merge（保留历史）
Rebase (선형 히스토리)
Rebase（线性历史）
Interactive Rebase (커밋 정리)
交互式Rebase（整理提交）
reword → 커밋 메시지 수정
reword → 修改提交消息
edit → 커밋 수정
edit → 修改提交内容
squash → 이전 커밋에 합침
squash → 合并到上一个提交
fixup → 이전 커밋에 합침 (메시지 제거)
fixup → 合并到上一个提交（丢弃当前提交消息）
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
pick d4e5f6g fix: typo in variable name
pick g7h8i9j fix: rename variable for clarity
After (squash 사용)
整理后（使用squash）
pick a1b2c3d feat: implement login feature
fixup d4e5f6g fix: typo in variable name
fixup 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 (브랜치 최신화)
基于main分支Rebase（更新分支）
git switch main
git pull origin main
git switch main
git pull origin main
2. feature 브랜치를 main 위로 rebase
2. 将feature分支Rebase到main分支上
git switch feature/my-feature
git rebase main
git switch feature/my-feature
git rebase main
git add .
git rebase --continue
git add .
git rebase --continue
- rebase 취소하고 싶다면
- 若要取消Rebase
Cherry-pick (특정 커밋만 가져오기)
Cherry-pick（仅引入特定提交）
다른 브랜치의 커밋 하나만 적용
仅应用其他分支的单个提交
git cherry-pick <commit-hash>
git cherry-pick <commit-hash>
git cherry-pick <commit-hash1> <commit-hash2>
git cherry-pick <commit-hash1> <commit-hash2>
git add .
git cherry-pick --continue
git add .
git cherry-pick --continue
Commit Amend (마지막 커밋 수정)
Commit Amend（修改最后一次提交）
마지막 커밋 메시지만 수정
仅修改最后一次提交的消息
git commit --amend -m "fix: correct commit message"
git commit --amend -m "fix: correct commit message"
마지막 커밋에 파일 추가
向最后一次提交中添加文件
git add forgotten-file.ts
git commit --amend --no-edit
git add forgotten-file.ts
git commit --amend --no-edit
⚠️ 주의: 이미 push한 커밋은 amend 금지 (히스토리 변경됨)
⚠️ 注意：已推送到远程的提交禁止使用amend（会修改历史记录）
Reset vs Revert
Reset vs Revert
Reset - 커밋 취소 (히스토리 삭제)
Reset - 撤销提交（删除历史记录）
git reset --soft HEAD1 # 커밋만 취소, 변경사항 유지
git reset --mixed HEAD1 # 커밋 + staging 취소, 변경사항 유지 (기본값)
git reset --hard HEAD~1 # 커밋 + 변경사항 모두 삭제 (위험!)
git reset --soft HEAD1 # 仅撤销提交，保留变更内容
git reset --mixed HEAD1 # 撤销提交和暂存，保留变更内容（默认值）
git reset --hard HEAD~1 # 撤销提交并删除所有变更内容（危险！）
⚠️ push한 커밋은 reset 금지 → revert 사용
⚠️ 已推送到远程的提交禁止使用reset → 请使用revert
Revert - 커밋을 되돌리는 새 커밋 생성 (히스토리 보존)
Revert - 生成新提交以撤销原有提交（保留历史记录）
git revert <commit-hash>
git revert HEAD # 마지막 커밋 되돌리기
git revert <commit-hash>
git revert HEAD # 撤销最后一次提交
main을 merge하거나 rebase할 때 충돌 발생
合并或Rebase main分支时发生冲突
Auto-merging src/index.ts
Auto-merging src/index.ts
CONFLICT (content): Merge conflict in src/index.ts
CONFLICT (content): Merge conflict in src/index.ts
2. 파일 열어서 수동 수정
2. 打开文件手动修改
<<<<<<< HEAD (현재 브랜치)
<<<<<<< HEAD (当前分支)
3. 마커 제거하고 코드 수정
3. 删除标记并修改代码
4. 해결된 파일 staging
4. 将解决后的文件加入暂存区
현재 브랜치 변경사항 우선
优先保留当前分支的变更
git restore --ours <file>
git restore --ours <file>
상대 브랜치 변경사항 우선
优先保留对方分支的变更
git restore --theirs <file>
git restore --theirs <file>
브랜치 작업 (git switch)
分支操作（git switch）
git switch main
git switch feature/my-feature
git switch main
git switch feature/my-feature
git switch -c feature/new-feature
git switch -c feature/new-feature
git switch -c local-branch origin/remote-branch
**참고**: Git 2.23+ (2019년 8월)부터 `git switch`를 사용한다. 기존 `git checkout`은 브랜치 전환, 파일 복원 등 여러 역할을 담당해 혼란을 야기했다. `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）
작업 디렉토리 파일 복원 (unstaged 변경사항 취소)
恢复工作区文件（撤销未暂存的变更）
Staging 취소 (unstaged로 되돌림)
取消暂存（将文件从暂存区放回工作区）
git restore --staged <file>
git restore --staged <file>
작업 디렉토리 + Staging 모두 복원
同时恢复工作区和暂存区
git restore --staged --worktree <file>
git restore --staged --worktree <file>
특정 커밋의 파일로 복원
将文件恢复到指定提交的状态
git restore --source=<commit-hash> <file>
**참고**: `git restore`는 파일 복원 전용 명령어다. 기존 `git checkout -- <file>`을 대체한다.
git restore --source=<commit-hash> <file>
**参考**：`git restore`是专门用于文件恢复的命令，替代了原有的`git checkout -- <file>`。
bash
git status # 변경사항 확인
git log --oneline # 커밋 히스토리 (한 줄)
git log --graph # 브랜치 그래프
git diff # 변경 내용 확인
git diff --staged # staging된 변경 내용
git show <commit-hash> # 특정 커밋 상세보기
bash
git status # 查看变更内容
git log --oneline # 查看提交历史（单行显示）
git log --graph # 查看分支图
git diff # 查看未暂存的变更
git diff --staged # 查看已暂存的变更
git show <commit-hash> # 查看特定提交的详细内容
bash
git stash # 현재 작업 임시 저장
git stash list # 저장된 stash 목록
git stash pop # 마지막 stash 적용 + 삭제
git stash apply # 마지막 stash 적용 (유지)
git stash drop # 마지막 stash 삭제
git stash clear # 모든 stash 삭제
bash
git stash # 临时存储当前工作内容
git stash list # 查看存储的stash列表
git stash pop # 应用最后一个stash并删除它
git stash apply # 应用最后一个stash（保留原stash）
git stash drop # 删除最后一个stash
git stash clear # 删除所有stash
bash
git remote -v # 원격 저장소 확인
git fetch origin # 원격 변경사항 가져오기 (병합 X)
git pull origin main # 원격 변경사항 가져오기 + 병합
git push origin main # 로컬 변경사항 푸시
git push -f origin main # 강제 푸시 (⚠️ 위험 - 팀 작업 시 금지)
bash
git remote -v # 查看远程仓库信息
git fetch origin # 获取远程变更（不合并）
git pull origin main # 获取远程变更并合并到本地
git push origin main # 将本地变更推送到远程
git push -f origin main # 强制推送（⚠️ 危险 - 团队协作时禁止使用）
.gitignore에 추가
添加到.gitignore中
.env # 환경 변수 (API 키, 비밀번호)
.env.local
*.key # 인증서 키
*.pem
secrets/ # 시크릿 디렉토리
node_modules/ # 의존성 (package.json으로 관리)
dist/ # 빌드 결과물
.DS_Store # macOS 시스템 파일
.env # 环境变量（API密钥、密码）
.env.local
*.key # 证书密钥
*.pem
secrets/ # 保密目录
node_modules/ # 依赖包（通过package.json管理）
dist/ # 构建产物
.DS_Store # macOS系统文件
실수로 커밋한 시크릿 제거
误提交敏感信息后的处理
⚠️ 히스토리에서 완전 삭제 (git filter-branch 대신 BFG 사용)
⚠️ 从历史记录中彻底删除（推荐使用BFG替代git filter-branch）
brew install bfg
bfg --delete-files .env
git reflog expire --expire=now --all && git gc --prune=now --aggressive
brew install bfg
bfg --delete-files .env
git reflog expire --expire=now --all && git gc --prune=now --aggressive
⚠️ 주의: 이미 푸시했다면 시크릿 즉시 폐기 후 재발급 필수
⚠️ 注意：若已推送到远程，需立即作废敏感信息并重新生成
Force Push 금지 (공유 브랜치)
禁止强制推送（共享分支）
❌ main/develop에 force push 절대 금지
❌ 绝对禁止对main/develop分支执行强制推送
✅ 개인 feature 브랜치에서만 허용
✅ 仅允许在个人feature分支使用
git push -f origin feature/my-branch
git push -f origin feature/my-branch
GitHub CLI 활용
GitHub CLI使用
gh pr create --title "feat: add new feature" --body "Description..."
gh pr create --title "feat: add new feature" --body "Description..."
PR 체크아웃 (로컬에서 테스트)
检出PR到本地测试
gh issue create --title "Bug found" --body "Description..."
gh issue create --title "Bug found" --body "Description..."