git

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git

Git 버전 관리 모범 관례 및 워크플로우 가이드.

Git版本管理最佳实践与工作流指南。

커밋 메시지 컨벤션

提交消息规范

Conventional Commits 사용

使用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

提交消息需遵循

<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`

类型	说明	示例
`feat`	添加新功能	`feat: add dark mode support`
`fix`	修复Bug	`fix: prevent token deletion on logout`
`docs`	修改文档（无代码变更）	`docs: update API documentation`
`style`	代码格式化、补充分号等（无功能变更）	`style: apply ESLint rules`
`refactor`	代码重构（无功能变更）	`refactor: extract utility functions`
`test`	添加/修改测试代码	`test: add login API tests`
`chore`	构建、配置变更（无源码变更）	`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

<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

자주 하는 실수

常见错误

bash

undefined

bash

undefined

❌ 타입 누락

❌ 缺少类型

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"

undefined

git commit -m "feat: add form validation to login page"

undefined

커밋 메시지 작성 가이드라인

提交消息编写指南

첫 줄은 50자 이내 - 간결한 요약
현재형 사용 - "added" (X) → "add" (O)
명령형 어조 - "adds" (X) → "add" (O)
첫 글자 소문자 -
```
Feat:
```
(X) →
```
feat:
```
(O)
마침표 금지 -
```
feat: add feature.
```
(X) →
```
feat: add feature
```
(O)
본문은 72자마다 줄바꿈 - 가독성 향상
Why > What - 변경한 내용보다 변경한 이유를 설명
영어로 작성 - 릴리즈 노트 생성 도구와의 호환성을 위해

首行不超过50字符 - 简洁总结
使用现在时 - "added"（错误）→ "add"（正确）
使用命令式语气 - "adds"（错误）→ "add"（正确）
首字母小写 -
```
Feat:
```
（错误）→
```
feat:
```
（正确）
末尾不加句号 -
```
feat: add feature.
```
（错误）→
```
feat: add feature
```
（正确）
正文每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

을 사용한다 (과거의

master

대신):

bash

undefined

创建新仓库时默认分支使用

main

（替代过去的

master

）：

bash

undefined

새 저장소 초기화 시 main 브랜치로 시작

初始化新仓库时以main分支启动

git init -b 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`作为默认分支。

브랜치 네이밍

分支命名

bash

undefined

bash

undefined

형식: <type>/<description>

格式: <type>/<description>

feature/user-authentication fix/header-layout-bug refactor/payment-module docs/api-documentation test/user-service chore/update-dependencies

undefined

feature/user-authentication fix/header-layout-bug refactor/payment-module docs/api-documentation test/user-service chore/update-dependencies

undefined

작업 흐름

工作流程

bash

undefined

bash

undefined

1. main에서 최신 상태 받기

1. 获取main分支的最新状态

git switch main git pull origin main

2. 새 브랜치 생성

2. 创建新分支

git switch -c feature/dark-mode

3. 작업 후 커밋

3. 完成工作后提交

git add . git commit -m "feat: add dark mode toggle button"

4. 원격 브랜치에 푸시

4. 推送到远程分支

git push origin feature/dark-mode

5. GitHub에서 PR 생성

5. 在GitHub上创建PR

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

undefined

git switch main git pull origin main git branch -d feature/dark-mode

undefined

PR 병합 전략

PR合并策略

전략	설명	언제 사용
Squash	모든 커밋을 하나로 합침	기능 브랜치 (권장)
Merge	병합 커밋 생성, 히스토리 보존	릴리스 브랜치
Rebase	선형 히스토리 유지, 병합 커밋 X	간단한 변경, 깔끔한 히스토리

bash

undefined

策略	说明	使用场景
Squash	将所有提交合并为一个	功能分支（推荐）
Merge	生成合并提交，保留历史记录	发布分支
Rebase	维持线性历史，无合并提交	简单变更、需要整洁历史时

bash

undefined

Squash (권장 - 기능 단위로 커밋 정리)

Squash（推荐 - 按功能单元整理提交）

gh pr merge 123 --squash

Merge (히스토리 보존)

Merge（保留历史）

gh pr merge 123 --merge

Rebase (선형 히스토리)

Rebase（线性历史）

gh pr merge 123 --rebase

undefined

gh pr merge 123 --rebase

undefined

Git 히스토리 관리

Git历史管理

Rebase

Interactive Rebase (커밋 정리)

交互式Rebase（整理提交）

bash

undefined

bash

undefined

최근 3개 커밋 수정

修改最近3个提交

git rebase -i HEAD~3

에디터에서 명령어 선택

在编辑器中选择命令

pick → 커밋 유지

pick → 保留提交

reword → 커밋 메시지 수정

reword → 修改提交消息

edit → 커밋 수정

edit → 修改提交内容

squash → 이전 커밋에 합침

squash → 合并到上一个提交

fixup → 이전 커밋에 합침 (메시지 제거)

fixup → 合并到上一个提交（丢弃当前提交消息）

drop → 커밋 삭제

drop → 删除提交


예시:

```bash


示例：

```bash

Before

整理前

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

undefined

pick a1b2c3d feat: implement login feature fixup d4e5f6g fix: typo in variable name fixup g7h8i9j fix: rename variable for clarity

undefined

Rebase onto main (브랜치 최신화)

基于main分支Rebase（更新分支）

bash

undefined

bash

undefined

1. main 최신화

1. 更新main分支

git switch main git pull origin main

2. feature 브랜치를 main 위로 rebase

2. 将feature分支Rebase到main分支上

git switch feature/my-feature git rebase main

3. 충돌 발생 시

3. 发生冲突时

- 파일 수정 후

- 修改文件后

git add . git rebase --continue

- rebase 취소하고 싶다면

- 若要取消Rebase

git rebase --abort

undefined

git rebase --abort

undefined

Cherry-pick (특정 커밋만 가져오기)

Cherry-pick（仅引入特定提交）

bash

undefined

bash

undefined

다른 브랜치의 커밋 하나만 적용

仅应用其他分支的单个提交

git cherry-pick <commit-hash>

여러 커밋 적용

应用多个提交

git cherry-pick <commit-hash1> <commit-hash2>

충돌 발생 시

发生冲突时

git add . git cherry-pick --continue

undefined

git add . git cherry-pick --continue

undefined

Commit Amend (마지막 커밋 수정)

Commit Amend（修改最后一次提交）

bash

undefined

bash

undefined

마지막 커밋 메시지만 수정

仅修改最后一次提交的消息

git commit --amend -m "fix: correct commit message"

마지막 커밋에 파일 추가

向最后一次提交中添加文件

git add forgotten-file.ts git commit --amend --no-edit

⚠️ 주의: 이미 push한 커밋은 amend 금지 (히스토리 변경됨)

⚠️ 注意：已推送到远程的提交禁止使用amend（会修改历史记录）

undefined

undefined

Reset vs Revert

bash

undefined

bash

undefined

Reset - 커밋 취소 (히스토리 삭제)

Reset - 撤销提交（删除历史记录）

git reset --soft HEAD~~1 # 커밋만 취소, 변경사항 유지 git reset --mixed HEAD~~1 # 커밋 + staging 취소, 변경사항 유지 (기본값) git reset --hard HEAD~1 # 커밋 + 변경사항 모두 삭제 (위험!)

git reset --soft HEAD~~1 # 仅撤销提交，保留变更内容 git reset --mixed HEAD~~1 # 撤销提交和暂存，保留变更内容（默认值） git reset --hard HEAD~1 # 撤销提交并删除所有变更内容（危险！）

⚠️ push한 커밋은 reset 금지 → revert 사용

⚠️ 已推送到远程的提交禁止使用reset → 请使用revert

Revert - 커밋을 되돌리는 새 커밋 생성 (히스토리 보존)

Revert - 生成新提交以撤销原有提交（保留历史记录）

git revert <commit-hash> git revert HEAD # 마지막 커밋 되돌리기

undefined

git revert <commit-hash> git revert HEAD # 撤销最后一次提交

undefined

Merge Conflict 해결

合并冲突解决

Conflict 발생 시나리오

冲突发生场景

bash

undefined

bash

undefined

main을 merge하거나 rebase할 때 충돌 발생

合并或Rebase main分支时发生冲突

git merge main

또는

或

git rebase main

Auto-merging src/index.ts

CONFLICT (content): Merge conflict in src/index.ts

undefined

undefined

Conflict 해결 과정

冲突解决流程

bash

undefined

bash

undefined

1. 충돌 파일 확인

1. 查看冲突文件

git status

2. 파일 열어서 수동 수정

2. 打开文件手动修改

<<<<<<< HEAD (현재 브랜치)

<<<<<<< HEAD (当前分支)

내 변경사항

我的变更内容

=======

상대 브랜치의 변경사항

对方分支的变更内容

>>>>>>> main

3. 마커 제거하고 코드 수정

3. 删除标记并修改代码

4. 해결된 파일 staging

4. 将解决后的文件加入暂存区

git add src/index.ts

5. Merge 완료

5. 完成合并

git merge --continue

또는 Rebase 계속

或继续Rebase

git rebase --continue

undefined

git rebase --continue

undefined

Conflict 해결 전략

冲突解决策略

bash

undefined

bash

undefined

현재 브랜치 변경사항 우선

优先保留当前分支的变更

git restore --ours <file>

상대 브랜치 변경사항 우선

优先保留对方分支的变更

git restore --theirs <file>

merge 취소

取消合并

git merge --abort

rebase 취소

取消Rebase

git rebase --abort

undefined

git rebase --abort

undefined

자주 사용하는 명령어

常用命令

브랜치 작업 (git switch)

分支操作（git switch）

bash

undefined

bash

undefined

기존 브랜치로 전환

切换到已有分支

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 switch -c local-branch origin/remote-branch


**参考**：Git 2.23+（2019年8月）开始支持`git switch`。原`git checkout`同时负责分支切换和文件恢复，容易造成混淆，`git switch`专门用于分支切换。

파일 복원 (git restore)

文件恢复（git restore）

bash

undefined

bash

undefined

작업 디렉토리 파일 복원 (unstaged 변경사항 취소)

恢复工作区文件（撤销未暂存的变更）

git restore <file>

Staging 취소 (unstaged로 되돌림)

取消暂存（将文件从暂存区放回工作区）

git restore --staged <file>

작업 디렉토리 + Staging 모두 복원

同时恢复工作区和暂存区

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>  # 查看特定提交的详细内容

Stash (임시 저장)

Stash（临时存储）

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 # 强制推送（⚠️ 危险 - 团队协作时禁止使用）

보안 및 주의사항

安全及注意事项

절대 커밋하면 안 되는 파일

绝对禁止提交的文件

bash

undefined

bash

undefined

.gitignore에 추가

添加到.gitignore中

.env # 환경 변수 (API 키, 비밀번호) .env.local *.key # 인증서 키 *.pem secrets/ # 시크릿 디렉토리 node_modules/ # 의존성 (package.json으로 관리) dist/ # 빌드 결과물 .DS_Store # macOS 시스템 파일

undefined

.env # 环境变量（API密钥、密码） .env.local *.key # 证书密钥 *.pem secrets/ # 保密目录 node_modules/ # 依赖包（通过package.json管理） dist/ # 构建产物 .DS_Store # macOS系统文件

undefined

실수로 커밋한 시크릿 제거

误提交敏感信息后的处理

bash

undefined

bash

undefined

⚠️ 히스토리에서 완전 삭제 (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

⚠️ 주의: 이미 푸시했다면 시크릿 즉시 폐기 후 재발급 필수

⚠️ 注意：若已推送到远程，需立即作废敏感信息并重新生成

undefined

undefined

Force Push 금지 (공유 브랜치)

禁止强制推送（共享分支）

bash

undefined

bash

undefined

❌ main/develop에 force push 절대 금지

❌ 绝对禁止对main/develop分支执行强制推送

git push -f origin main

✅ 개인 feature 브랜치에서만 허용

✅ 仅允许在个人feature分支使用

git push -f origin feature/my-branch

undefined

git push -f origin feature/my-branch

undefined

GitHub CLI 활용

GitHub CLI使用

bash

undefined

bash

undefined

PR 생성

创建PR

gh pr create --title "feat: add new feature" --body "Description..."

PR 목록 확인

查看PR列表

gh pr list

PR 상세보기

查看PR详情

gh pr view 123

PR 체크아웃 (로컬에서 테스트)

检出PR到本地测试

gh pr checkout 123

PR 병합

合并PR

gh pr merge 123 --squash

Issue 생성

创建Issue

gh issue create --title "Bug found" --body "Description..."

undefined

gh issue create --title "Bug found" --body "Description..."

undefined