483 lines
8.5 KiB
Markdown
483 lines
8.5 KiB
Markdown
# Git 使用规范
|
||
|
||
## 目录
|
||
- [分支命名规范](#分支命名规范)
|
||
- [提交信息规范](#提交信息规范)
|
||
- [工作流程](#工作流程)
|
||
- [代码审查](#代码审查)
|
||
- [最佳实践](#最佳实践)
|
||
|
||
---
|
||
|
||
## 分支命名规范
|
||
|
||
### 分支类型
|
||
|
||
#### 1. 主分支
|
||
- **master/main**: 生产环境分支，只接受合并，不允许直接提交
|
||
- **develop/dev**: 开发主分支，用于集成所有功能
|
||
|
||
#### 2. 功能分支 (Feature)
|
||
```
|
||
feature/功能名称
|
||
feature/功能名称-简短描述
|
||
```
|
||
**示例：**
|
||
- `feature/user-login`
|
||
- `feature/payment-integration`
|
||
- `feature/contacts-friends`
|
||
|
||
#### 3. 修复分支 (Bugfix)
|
||
```
|
||
bugfix/问题描述
|
||
fix/问题描述
|
||
```
|
||
**示例：**
|
||
- `bugfix/login-error`
|
||
- `fix/memory-leak`
|
||
|
||
#### 4. 热修复分支 (Hotfix)
|
||
```
|
||
hotfix/问题描述
|
||
```
|
||
**示例：**
|
||
- `hotfix/critical-security-patch`
|
||
- `hotfix/payment-bug`
|
||
|
||
#### 5. 发布分支 (Release)
|
||
```
|
||
release/版本号
|
||
```
|
||
**示例：**
|
||
- `release/v1.0.0`
|
||
- `release/v2.1.0`
|
||
|
||
### 命名规则
|
||
- 使用小写字母
|
||
- 多个单词用连字符 `-` 分隔
|
||
- 避免使用下划线 `_` 或空格
|
||
- 分支名要有意义，能清楚表达分支用途
|
||
- 避免使用特殊字符：`~`, `^`, `:`, `?`, `*`, `[`, `\`
|
||
|
||
---
|
||
|
||
## 提交信息规范
|
||
|
||
### 提交信息格式
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### Type 类型
|
||
|
||
| 类型 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `feat` | 新功能 | `feat: 添加用户登录功能` |
|
||
| `fix` | 修复bug | `fix: 修复登录验证失败问题` |
|
||
| `docs` | 文档更新 | `docs: 更新API文档` |
|
||
| `style` | 代码格式调整（不影响功能） | `style: 格式化代码` |
|
||
| `refactor` | 代码重构 | `refactor: 重构用户服务类` |
|
||
| `perf` | 性能优化 | `perf: 优化数据库查询性能` |
|
||
| `test` | 测试相关 | `test: 添加用户登录单元测试` |
|
||
| `chore` | 构建/工具/依赖更新 | `chore: 更新依赖包版本` |
|
||
| `ci` | CI/CD相关 | `ci: 配置GitHub Actions` |
|
||
| `build` | 构建系统相关 | `build: 更新Maven配置` |
|
||
|
||
### Scope 范围（可选）
|
||
- 指定修改的模块或文件
|
||
- 示例：`feat(user): 添加用户注册功能`
|
||
|
||
### Subject 主题
|
||
- 简短描述，不超过50个字符
|
||
- 使用中文或英文，保持项目统一
|
||
- 首字母小写，结尾不加句号
|
||
- 使用祈使语气（如：添加、修复、更新）
|
||
|
||
### Body 正文（可选）
|
||
- 详细描述修改内容
|
||
- 说明为什么修改，如何修改
|
||
- 每行不超过72个字符
|
||
- 用空行与 subject 分隔
|
||
|
||
### Footer 页脚（可选）
|
||
- 关联Issue：`Closes #123`
|
||
- 破坏性变更：`BREAKING CHANGE: 修改了API接口`
|
||
|
||
### 提交信息示例
|
||
|
||
#### 简单提交
|
||
```
|
||
feat: 添加联系人管理功能
|
||
```
|
||
|
||
#### 带scope的提交
|
||
```
|
||
feat(user): 添加用户头像上传功能
|
||
```
|
||
|
||
#### 详细提交
|
||
```
|
||
feat(contact): 添加联系人管理功能
|
||
|
||
- 实现联系人列表查询
|
||
- 添加联系人添加/删除接口
|
||
- 集成Redis缓存优化性能
|
||
|
||
Closes #45
|
||
```
|
||
|
||
#### 修复提交
|
||
```
|
||
fix: 修复登录验证失败问题
|
||
|
||
修复了当用户密码包含特殊字符时验证失败的问题
|
||
|
||
Fixes #67
|
||
```
|
||
|
||
---
|
||
|
||
## 工作流程
|
||
|
||
### 1. 创建功能分支
|
||
|
||
```bash
|
||
# 从develop分支创建新分支
|
||
git checkout develop
|
||
git pull origin develop
|
||
git checkout -b feature/your-feature-name
|
||
```
|
||
|
||
### 2. 开发过程
|
||
|
||
```bash
|
||
# 经常提交代码
|
||
git add .
|
||
git commit -m "feat: 实现XXX功能"
|
||
|
||
# 定期同步主分支
|
||
git checkout develop
|
||
git pull origin develop
|
||
git checkout feature/your-feature-name
|
||
git merge develop
|
||
```
|
||
|
||
### 3. 提交前检查
|
||
|
||
```bash
|
||
# 检查代码状态
|
||
git status
|
||
|
||
# 查看修改内容
|
||
git diff
|
||
|
||
# 查看提交历史
|
||
git log --oneline
|
||
```
|
||
|
||
### 4. 推送分支
|
||
|
||
```bash
|
||
# 首次推送
|
||
git push -u origin feature/your-feature-name
|
||
|
||
# 后续推送
|
||
git push
|
||
```
|
||
|
||
### 5. 合并到主分支
|
||
|
||
```bash
|
||
# 方式1: 通过Pull Request（推荐）
|
||
# 在Git平台创建PR，代码审查后合并
|
||
|
||
# 方式2: 本地合并（不推荐，除非紧急情况）
|
||
git checkout develop
|
||
git pull origin develop
|
||
git merge feature/your-feature-name
|
||
git push origin develop
|
||
```
|
||
|
||
### 6. 清理分支
|
||
|
||
```bash
|
||
# 删除本地分支
|
||
git branch -d feature/your-feature-name
|
||
|
||
# 删除远程分支
|
||
git push origin --delete feature/your-feature-name
|
||
```
|
||
|
||
---
|
||
|
||
## 代码审查
|
||
|
||
### Pull Request 规范
|
||
|
||
#### PR标题格式
|
||
```
|
||
[类型] 简短描述
|
||
```
|
||
**示例：**
|
||
- `[Feature] 添加联系人管理功能`
|
||
- `[Fix] 修复登录验证问题`
|
||
- `[Refactor] 重构用户服务类`
|
||
|
||
#### PR描述模板
|
||
```markdown
|
||
## 变更说明
|
||
简要描述本次PR的主要变更内容
|
||
|
||
## 变更类型
|
||
- [ ] 新功能
|
||
- [ ] Bug修复
|
||
- [ ] 代码重构
|
||
- [ ] 文档更新
|
||
- [ ] 性能优化
|
||
- [ ] 其他
|
||
|
||
## 测试说明
|
||
描述如何测试这些变更
|
||
|
||
## 相关Issue
|
||
关联的Issue编号: #123
|
||
|
||
## 截图（如适用）
|
||
[添加相关截图]
|
||
```
|
||
|
||
### 审查检查清单
|
||
|
||
#### 提交者
|
||
- [ ] 代码符合项目规范
|
||
- [ ] 已添加必要的测试
|
||
- [ ] 已更新相关文档
|
||
- [ ] 提交信息清晰明确
|
||
- [ ] 无编译错误和警告
|
||
- [ ] 已进行自测
|
||
|
||
#### 审查者
|
||
- [ ] 代码逻辑正确
|
||
- [ ] 代码风格一致
|
||
- [ ] 无明显的性能问题
|
||
- [ ] 无安全隐患
|
||
- [ ] 测试覆盖充分
|
||
- [ ] 文档更新完整
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 提交频率
|
||
- ✅ **推荐**: 频繁提交，每次提交完成一个小功能
|
||
- ❌ **不推荐**: 大量代码一次性提交
|
||
|
||
### 2. 提交粒度
|
||
- ✅ **推荐**: 每次提交只做一件事
|
||
- ❌ **不推荐**: 一个提交包含多个不相关的修改
|
||
|
||
### 3. 提交前检查
|
||
```bash
|
||
# 检查代码格式
|
||
# 运行测试
|
||
# 检查编译错误
|
||
```
|
||
|
||
### 4. 避免的操作
|
||
- ❌ 不要在master/main分支直接提交
|
||
- ❌ 不要提交临时文件、日志文件
|
||
- ❌ 不要提交敏感信息（密码、密钥等）
|
||
- ❌ 不要强制推送主分支 (`git push --force`)
|
||
|
||
### 5. 使用 .gitignore
|
||
确保 `.gitignore` 文件包含：
|
||
```
|
||
# 编译文件
|
||
*.class
|
||
*.jar
|
||
*.war
|
||
|
||
# IDE文件
|
||
.idea/
|
||
.vscode/
|
||
*.iml
|
||
|
||
# 日志文件
|
||
*.log
|
||
|
||
# 依赖目录
|
||
node_modules/
|
||
target/
|
||
|
||
# 配置文件（包含敏感信息）
|
||
application-local.yml
|
||
config.properties
|
||
```
|
||
|
||
### 6. 冲突处理
|
||
```bash
|
||
# 拉取最新代码
|
||
git pull origin develop
|
||
|
||
# 如果有冲突，解决冲突后
|
||
git add .
|
||
git commit -m "fix: 解决合并冲突"
|
||
```
|
||
|
||
### 7. 撤销操作
|
||
|
||
#### 撤销工作区修改
|
||
```bash
|
||
git checkout -- <file>
|
||
```
|
||
|
||
#### 撤销暂存区修改
|
||
```bash
|
||
git reset HEAD <file>
|
||
```
|
||
|
||
#### 修改最后一次提交
|
||
```bash
|
||
git commit --amend -m "新的提交信息"
|
||
```
|
||
|
||
#### 回退到指定提交
|
||
```bash
|
||
# 软回退（保留修改）
|
||
git reset --soft <commit-hash>
|
||
|
||
# 硬回退（丢弃修改）
|
||
git reset --hard <commit-hash>
|
||
```
|
||
|
||
---
|
||
|
||
## 常用命令速查
|
||
|
||
### 分支操作
|
||
```bash
|
||
# 查看所有分支
|
||
git branch -a
|
||
|
||
# 创建分支
|
||
git branch <branch-name>
|
||
|
||
# 切换分支
|
||
git checkout <branch-name>
|
||
|
||
# 创建并切换分支
|
||
git checkout -b <branch-name>
|
||
|
||
# 删除本地分支
|
||
git branch -d <branch-name>
|
||
|
||
# 删除远程分支
|
||
git push origin --delete <branch-name>
|
||
```
|
||
|
||
### 提交操作
|
||
```bash
|
||
# 查看状态
|
||
git status
|
||
|
||
# 添加文件
|
||
git add <file>
|
||
git add .
|
||
|
||
# 提交
|
||
git commit -m "提交信息"
|
||
|
||
# 查看提交历史
|
||
git log
|
||
git log --oneline
|
||
git log --graph --oneline --all
|
||
```
|
||
|
||
### 远程操作
|
||
```bash
|
||
# 查看远程仓库
|
||
git remote -v
|
||
|
||
# 拉取代码
|
||
git pull origin <branch-name>
|
||
|
||
# 推送代码
|
||
git push origin <branch-name>
|
||
|
||
# 获取远程更新（不合并）
|
||
git fetch origin
|
||
```
|
||
|
||
### 其他实用命令
|
||
```bash
|
||
# 查看差异
|
||
git diff
|
||
git diff <branch1> <branch2>
|
||
|
||
# 暂存修改
|
||
git stash
|
||
git stash pop
|
||
|
||
# 查看文件历史
|
||
git log -- <file>
|
||
|
||
# 查看某行的修改历史
|
||
git blame <file>
|
||
```
|
||
|
||
---
|
||
|
||
## 版本标签规范
|
||
|
||
### 标签命名
|
||
使用语义化版本号：`v主版本号.次版本号.修订号`
|
||
|
||
**示例：**
|
||
- `v1.0.0` - 初始发布
|
||
- `v1.1.0` - 新功能
|
||
- `v1.1.1` - Bug修复
|
||
- `v2.0.0` - 重大更新
|
||
|
||
### 标签操作
|
||
```bash
|
||
# 创建标签
|
||
git tag -a v1.0.0 -m "版本1.0.0发布"
|
||
|
||
# 推送标签
|
||
git push origin v1.0.0
|
||
|
||
# 推送所有标签
|
||
git push origin --tags
|
||
|
||
# 查看标签
|
||
git tag
|
||
git show v1.0.0
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **保护主分支**: master/main 分支应该设置保护规则，禁止直接推送
|
||
2. **定期同步**: 开发过程中定期从主分支同步代码，避免冲突积累
|
||
3. **及时清理**: 合并后的分支及时删除，保持仓库整洁
|
||
4. **提交前测试**: 确保代码可以正常编译和运行
|
||
5. **代码审查**: 重要功能必须经过代码审查才能合并
|
||
|
||
---
|
||
|
||
## 参考资源
|
||
|
||
- [Git官方文档](https://git-scm.com/doc)
|
||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||
- [Semantic Versioning](https://semver.org/)
|
||
|
||
---
|
||
|
||
**最后更新**: 2024年
|
||
|