git-workflow

Git 工作流规范

本文档定义了项目的 Git 使用规范，包括提交消息格式、分支管理策略、工作流、合并策略等。遵循这些规范有助于提高协作效率、实现可追溯性、支持自动化并减少冲突。

提交消息规范

项目遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

类型参考

类型	描述	示例
feat	新功能	feat(user): add user export functionality
fix	修复错误	fix(login): fix captcha not refreshing
docs	更新文档	docs(api): update API documentation
refactor	重构	refactor(utils): refactor utility functions
perf	性能改进	perf(list): optimize list performance
test	测试相关	test(user): add unit tests
chore	其他更改	chore: update dependency versions

主题规则

• 以动词开头：add、fix、update、remove、optimize
• 不超过 50 个字符
• 末尾不加句号

如需了解更详细的约定和示例，请参阅 references/commit-conventions.md。

分支管理策略

分支类型

分支类型	命名约定	描述	生命周期
master	master	主分支，可发布状态	永久
develop	develop	开发分支，最新集成代码	永久
feature	feature/feature-name	功能分支	完成后删除
bugfix	bugfix/issue-description	错误修复分支	修复后删除
hotfix	hotfix/issue-description	紧急修复分支	修复后删除
release	release/version-number	发布分支	发布后删除

分支命名示例

feature/user-management          # User management feature
feature/123-add-export          # Issue-linked feature
bugfix/login-error              # Login error fix
hotfix/security-vulnerability   # Security vulnerability fix
release/v1.0.0                  # Version release

分支保护规则

master 分支：

• 不允许直接推送
• 必须通过 Pull Request 合并
• 必须通过 CI 检查
• 至少需要一名 Code Review 审核者批准

develop 分支：

• 限制直接推送
• 建议通过 Pull Request 合并
• 必须通过 CI 检查

如需了解详细的分支策略和工作流，请参阅 references/branching-strategies.md。

工作流

日常开发工作流

# 1. Sync latest code
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/user-management

# 3. Develop and commit
git add .
git commit -m "feat(user): add user list page"

# 4. Push to remote
git push -u origin feature/user-management

# 5. Create Pull Request and request Code Review

# 6. Merge to develop (via PR)

# 7. Delete feature branch
git branch -d feature/user-management
git push origin -d feature/user-management

热修复工作流

# 1. Create fix branch from master
git checkout master
git pull origin master
git checkout -b hotfix/critical-bug

# 2. Fix and commit
git add .
git commit -m "fix(auth): fix authentication bypass vulnerability"

# 3. Merge to master
git checkout master
git merge --no-ff hotfix/critical-bug
git tag -a v1.0.1 -m "hotfix: fix authentication bypass vulnerability"
git push origin master --tags

# 4. Sync to develop
git checkout develop
git merge --no-ff hotfix/critical-bug
git push origin develop

发布工作流

# 1. Create release branch
git checkout develop
git checkout -b release/v1.0.0

# 2. Update version numbers and documentation

# 3. Commit version update
git add .
git commit -m "chore(release): prepare release v1.0.0"

# 4. Merge to master
git checkout master
git merge --no-ff release/v1.0.0
git tag -a v1.0.0 -m "release: v1.0.0 official release"
git push origin master --tags

# 5. Sync to develop
git checkout develop
git merge --no-ff release/v1.0.0
git push origin develop

合并策略

Merge 与 Rebase

特性	Merge	Rebase
历史记录	保留完整历史	线性历史
使用场景	公共分支	私有分支
推荐用于	合并到主分支	同步上游代码

建议

• 功能分支同步 develop：使用 rebase
• 功能分支合并到 develop：使用 merge --no-ff
• develop 合并到 master：使用 merge --no-ff

# ✅ Recommended: Feature branch syncing develop
git checkout feature/user-management
git rebase develop

# ✅ Recommended: Merge feature branch to develop
git checkout develop
git merge --no-ff feature/user-management

# ❌ Not recommended: Rebase on public branch
git checkout develop
git rebase feature/xxx  # Dangerous operation

项目约定：将功能分支合并时使用 --no-ff，以保留分支历史。

如需了解详细的合并策略和技巧，请参阅 references/merge-strategies.md。

冲突解决

识别冲突

<<<<<<< HEAD
// Current branch code
const name = 'Alice'
=======
// Branch being merged
const name = 'Bob'
>>>>>>> feature/user-management

解决冲突

# 1. View conflicting files
git status

# 2. Manually edit files to resolve conflicts

# 3. Mark as resolved
git add <file>

# 4. Complete the merge
git commit  # merge conflict
# or
git rebase --continue  # rebase conflict

冲突解决策略

# Keep current branch version
git checkout --ours <file>

# Keep incoming branch version
git checkout --theirs <file>

# Abort merge
git merge --abort
git rebase --abort

预防冲突

1. 定期同步代码 - 每天开始工作前拉取最新代码
2. 小步提交 - 经常提交小幅更改
3. 模块化功能 - 在不同文件中实现不同功能
4. 沟通 - 避免同时修改同一个文件

如需了解详细的冲突处理和高级技巧，请参阅 references/conflict-resolution.md。

.gitignore 规范

基本规则

# Ignore all .log files
*.log

# Ignore directories
node_modules/

# Ignore directory at root
/temp/

# Ignore files in all directories
**/.env

# Don't ignore specific files
!.gitkeep

常见 .gitignore

node_modules/
dist/
build/
.idea/
.vscode/
.env
.env.local
logs/
*.log
.DS_Store
Thumbs.db

如需了解详细的 .gitignore 模式和项目专属配置，请参阅 references/gitignore-guide.md。

标签管理

采用 Semantic Versioning：

MAJOR.MINOR.PATCH[-PRERELEASE]

版本变更规则

• MAJOR：不兼容的 API 变更（v1.0.0 → v2.0.0）
• MINOR：向后兼容的新功能（v1.0.0 → v1.1.0）
• PATCH：向后兼容的错误修复（v1.0.0 → v1.0.1）

标签操作

# Create annotated tag (recommended)
git tag -a v1.0.0 -m "release: v1.0.0 official release"

# Push tags
git push origin v1.0.0
git push origin --tags

# View tags
git tag
git show v1.0.0

# Delete tag
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

团队协作规范

Pull Request 规范

PR 应包含：

## Change Description


## Change Type
- [ ] New feature (feat)
- [ ] Bug fix (fix)
- [ ] Code refactoring (refactor)

## Testing Method


## Related Issue
Closes #xxx

## Checklist
- [ ] Code has been self-tested
- [ ] Documentation has been updated

代码审查规范

审查重点：

• 代码质量：清晰易读、命名恰当、无重复代码
• 逻辑正确性：业务逻辑正确，并处理边界情况
• 安全性：无安全漏洞，保护敏感信息
• 性能：无明显性能问题，妥善释放资源

有关详细的协作规范和最佳实践，请参阅 references/collaboration.md。

常见问题

修改上一次提交

# Amend commit content (not yet pushed)
git add forgotten-file.ts
git commit --amend --no-edit

# Amend commit message
git commit --amend -m "new commit message"

推送被拒绝

# Pull then push
git pull origin master
git push origin master

# Use rebase for cleaner history
git pull --rebase origin master
git push origin master

回滚到之前的版本

# Reset to specific commit (discards subsequent commits)
git reset --hard abc123

# Create reverse commit (recommended, preserves history)
git revert abc123

暂存当前工作

git stash save "work in progress"
git stash list
git stash pop

查看文件修改历史

git log -- <file>             # Commit history
git log -p -- <file>          # Detailed content
git blame <file>              # Per-line author

最佳实践总结

提交规范

✅ 推荐：

• 遵循 Conventional Commits 规范
• 编写清晰的提交消息，说明所做更改
• 一次提交只包含一项逻辑更改
• 提交前运行代码检查

❌ 禁止：

• 使用含糊的提交消息
• 在一次提交中包含多个无关更改
• 提交敏感信息（密码、密钥）
• 直接在 main 分支上开发

分支管理

✅ 推荐：

• 使用功能分支进行开发
• 定期同步 main 分支代码
• 功能完成后及时删除分支
• 使用 --no-ff 合并以保留历史记录

❌ 禁止：

• 直接在 main 分支上开发
• 长期保留未合并的功能分支
• 使用不规范的分支命名
• 在公共分支上执行变基

代码审查

✅ 推荐：

• 所有代码都通过 Pull Request 提交
• 合并前至少获得一位审查者的批准
• 提供有建设性的反馈

❌ 禁止：

• 未经审查就合并
• 审查自己的代码

其他资源

参考文件

有关特定主题的详细指南：

• references/commit-conventions.md - 提交消息的详细规范和示例
• references/branching-strategies.md - 全面的分支管理策略
• references/merge-strategies.md - 合并、变基和冲突解决策略
• references/conflict-resolution.md - 详细的冲突处理与预防方法
• references/advanced-usage.md - Git 性能优化、安全性、子模块和高级技巧
• references/collaboration.md - Pull Request 和代码审查指南
• references/gitignore-guide.md - .gitignore 模式和项目专属配置

示例文件

examples/ 中的可用示例：

• examples/commit-messages.txt - 优质提交消息示例
• examples/workflow-commands.sh - 常用工作流命令片段

总结

本文档定义了项目的 Git 规范：

1. 提交消息 - 遵循 Conventional Commits 规范
2. 分支管理 - master/develop/feature/bugfix/hotfix/release 分支策略
3. 工作流 - 日常开发、紧急修复和发布的标准流程
4. 合并策略 - 使用 rebase 同步功能分支，使用 merge --no-ff 进行合并
5. 标签管理 - 语义化版本控制、附注标签
6. 冲突解决 - 定期同步、小规模提交、团队沟通

遵循这些规范有助于提高协作效率、确保代码质量并简化版本管理。