name: git-workflow description: 当用户询问"创建 git 提交"、“管理分支”、“遵循 git 工作流程”、“使用 Conventional Commits”、“处理合并冲突”，或询问 git 分支策略、版本控制最佳实践、pull request 工作流程时，应使用此技能。提供团队协作的全面 Git 工作流程指导。 version: 1.2.0

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          # 用户管理功能
feature/123-add-export          # 问题链接功能
bugfix/login-error              # 登录错误修复
hotfix/security-vulnerability   # 安全漏洞修复
release/v1.0.0                  # 版本发布

分支保护规则

master 分支:

不允许直接推送
必须通过 Pull Request 合并
必须通过 CI 检查
需要至少一个代码审查批准

develop 分支:

直接推送受限
推荐使用 Pull Request 合并
必须通过 CI 检查

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

工作流程

日常开发工作流程

# 1. 同步最新代码
git checkout develop
git pull origin develop

# 2. 创建功能分支
git checkout -b feature/user-management

# 3. 开发和提交
git add .
git commit -m "feat(user): add user list page"

# 4. 推送到远程
git push -u origin feature/user-management

# 5. 创建 Pull Request 并请求代码审查

# 6. 合并到 develop（通过 PR）

# 7. 删除功能分支
git branch -d feature/user-management
git push origin -d feature/user-management

热修复工作流程

# 1. 从 master 创建修复分支
git checkout master
git pull origin master
git checkout -b hotfix/critical-bug

# 2. 修复和提交
git add .
git commit -m "fix(auth): fix authentication bypass vulnerability"

# 3. 合并到 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. 同步到 develop
git checkout develop
git merge --no-ff hotfix/critical-bug
git push origin develop

发布工作流程

# 1. 创建发布分支
git checkout develop
git checkout -b release/v1.0.0

# 2. 更新版本号和文档

# 3. 提交版本更新
git add .
git commit -m "chore(release): prepare release v1.0.0"

# 4. 合并到 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. 同步到 develop
git checkout develop
git merge --no-ff release/v1.0.0
git push origin develop

合并策略

合并与变基

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

冲突解决

识别冲突

<<<<<<< HEAD
// 当前分支代码
const name = 'Alice'
=======
// 正在合并的分支
const name = 'Bob'
>>>>>>> feature/user-management

解决冲突

# 1. 查看冲突文件
git status

# 2. 手动编辑文件解决冲突

# 3. 标记为已解决
git add <file>

# 4. 完成合并
git commit  # 合并冲突
# 或
git rebase --continue  # 变基冲突

冲突解决策略

# 保留当前分支版本
git checkout --ours <file>

# 保留传入分支版本
git checkout --theirs <file>

# 中止合并
git merge --abort
git rebase --abort

预防冲突

定期同步代码 - 每天开始工作前拉取最新代码
小提交 - 频繁提交小更改
模块化功能 - 在不同文件中实现不同功能
沟通 - 避免同时修改同一文件

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

.gitignore 标准

基本规则

# 忽略所有 .log 文件
*.log

# 忽略目录
node_modules/

# 忽略根目录的目录
/temp/

# 忽略所有目录中的文件
**/.env

# 不忽略特定文件
!.gitkeep

常见 .gitignore

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

详细的 .gitignore 模式和项目特定配置，请参阅 references/gitignore-guide.md。

标签管理

使用 语义版本控制：

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）

标签操作

# 创建注释标签（推荐）
git tag -a v1.0.0 -m "release: v1.0.0 official release"

# 推送标签
git push origin v1.0.0
git push origin --tags

# 查看标签
git tag
git show v1.0.0

# 删除标签
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

团队协作标准

Pull Request 标准

PR 应包括：

## 更改描述
<!-- 描述此更改的内容和目的 -->

## 更改类型
- [ ] 新功能 (feat)
- [ ] 错误修复 (fix)
- [ ] 代码重构 (refactor)

## 测试方法
<!-- 描述如何测试 -->

## 相关问题
Closes #xxx

## 检查清单
- [ ] 代码已自测
- [ ] 文档已更新

代码审查标准

审查重点领域：

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

详细的协作标准和最佳实践，请参阅 references/collaboration.md。

常见问题

修改最后一次提交

# 修改提交内容（尚未推送）
git add forgotten-file.ts
git commit --amend --no-edit

# 修改提交消息
git commit --amend -m "new commit message"

推送被拒绝

# 拉取后推送
git pull origin master
git push origin master

# 使用变基以获得更干净的历史
git pull --rebase origin master
git push origin master

回滚到先前版本

# 重置到特定提交（丢弃后续提交）
git reset --hard abc123

# 创建反向提交（推荐，保留历史）
git revert abc123

暂存当前工作

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

查看文件修改历史

git log -- <file>             # 提交历史
git log -p -- <file>          # 详细内容
git blame <file>              # 每行作者

最佳实践总结

提交标准

✅ 推荐：

遵循 Conventional Commits 规范
编写清晰的提交消息描述更改
一个提交对应一个逻辑更改
提交前运行代码检查

❌ 禁止：

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

分支管理

✅ 推荐：

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

❌ 禁止：

直接在主分支上开发
长期未合并的功能分支
非标准分支命名
在公共分支上变基

代码审查

✅ 推荐：

所有代码都通过 Pull Requests
合并前至少一个审查者批准
提供建设性反馈

❌ 禁止：

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

额外资源

参考文件

特定主题的详细指导：

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 标准：

提交消息 - 遵循 Conventional Commits 规范
分支管理 - master/develop/feature/bugfix/hotfix/release 分支策略
工作流程 - 日常开发、热修复和发布的标准流程
合并策略 - 使用变基同步功能分支，使用 merge --no-ff 合并
标签管理 - 语义版本控制，注释标签
冲突解决 - 定期同步，小提交，团队沟通

遵循这些标准可以提高协作效率，确保代码质量，并简化版本管理。