Skip to content

git.md

Latest commit

 

History

History
157 lines (116 loc) · 5.75 KB

git.md

File metadata and controls

157 lines (116 loc) · 5.75 KB

Git 最佳实践规范

本规范旨在概述 Git 的使用最佳实践，以维护一个清晰、可理解且高效的版本控制历史。请在日常 Git 工作流程中遵循此指南。

1. Commit 提交规范

清晰、一致的 Commit 消息是理解项目历史的关键。

1.1 良好 Commit 消息的七大规则

  1. 使用空行分隔标题和正文。
  2. 限制标题长度在50个字符以内，以便在简短日志中完整显示。
  3. 标题首字母大写。
  4. 标题结尾不加句号。
  5. 在标题中使用祈使句 (例如, 使用 Add feature 而不是 Added feature)。
  6. 正文内容每行不超过72个字符，确保在各种Git工具中都易于阅读。
  7. 使用正文解释"是什么"和"为什么"，而不是"怎么做"。代码本身已经展示了"怎么做"。

1.2 Conventional Commits 约定

强烈推荐采用 Conventional Commits 规范，它能够生成结构化、易于人和机器阅读的提交消息。

格式:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

常用类型:

  • feat: 新增功能
  • fix: 修复 bug
  • docs: 仅修改文档
  • style: 代码格式修改 (不影响代码逻辑)
  • refactor: 代码重构
  • perf: 性能优化
  • test: 新增或修改测试
  • build: 影响构建系统或外部依赖的更改
  • ci: CI/CD 配置文件和脚本的更改
  • chore: 其他不修改 src 或 test 文件的更改
  • revert: 撤销之前的提交

示例:

feat(auth): Add Google OAuth2 login functionality

Implement the full OAuth2 flow for Google authentication. This allows users to sign up and log in with their Google accounts, improving the user experience.

Closes #123

2. 分支策略

一致的分支策略可以防止仓库历史变得混乱。

2.1 分支命名约定

使用清晰、描述性的命名约定，推荐使用类型前缀。

  • 功能分支: feat/user-authentication 或 feature/user-auth
  • 修复分支: fix/login-button-bug
  • 杂项/重构: chore/update-dependencies 或 refactor/api-service-layer

2.2 功能分支工作流

  1. 从主分支创建新分支 (main 或 master)。 
    git checkout main
git pull origin main
git checkout -b feat/new-shiny-feature
  2. 在功能分支上提交更改。
  3. 将分支推送到远程仓库。 
    git push -u origin feat/new-shiny-feature
  4. 创建 Pull Request (PR) 将功能分支合并到 main。
  5. 合并后删除分支。

2.3 分支最佳实践

  • 保持分支的生命周期短暂。一旦准备就绪就尽快合并。
  • 经常从 main 拉取更新 到你的功能分支，以避免巨大的合并冲突。 
    # 在你的功能分支上执行
git pull origin main --rebase
  • 删除已合并的分支 (本地和远程)。 
    # PR 合并后
git checkout main
git pull
git branch -d feat/new-shiny-feature
git push origin --delete feat/new-shiny-feature

3. Pull Requests (PRs) 规范

PR 是团队协作的基石。

  • 创建小而专注的 PR：一个 PR 只解决一个问题。小 PR 更容易、更快速地被审查。
  • 编写清晰的描述：使用 PR 模板解释你所做更改的"是什么"和"为什么"。对于UI更改，附上截图或GIF。
  • 关联 Issue：如果 PR 解决了某个 Issue，请关联它 (例如, "Closes #123")。
  • 要求代码审查：合并前至少需要一位其他成员审查并批准。
  • 确保 CI 检查通过：所有自动化检查 (测试、代码风格检查) 必须通过。

4. 合并策略

合并 PR 的方式极大地影响项目历史的清晰度。

  • 保护主分支：绝不直接向 main 分支推送代码。所有更改必须通过 PR。
  • 优先使用 Squash and Merge：这将功能分支上的所有提交压缩成一个干净的提交记录合并到 main 分支。这使得历史记录易于阅读和回滚。
  • 使用 Rebase and Merge：如果你希望保持一个完全线性的历史记录，可以使用此方法。它会将功能分支的提交"重放"到 main 分支的顶部。
  • 避免在 main 上使用普通的 merge commit，因为它会产生"合并气泡"，使历史记录变得混乱。

创建 PR 前：整理你的本地提交

在推送和创建 PR 之前，使用交互式变基 (git rebase -i) 来清理你的本地提交历史。你可以将小的、"进行中"的提交压缩成更大、更有意义的提交。

# 整理最近的3个提交
git rebase -i HEAD~3

5. 通用最佳实践与技巧

  • 善用 .gitignore：积极维护你的 .gitignore 文件，以防止将无关文件（如 .env、构建产物、IDE配置文件）提交到仓库中。
  • 避免提交大文件：不要提交大型二进制文件、数据库或编译后的代码。如果需要对大文件进行版本控制，请使用 Git LFS (Large File Storage)。
  • 保持更新：使用 git pull --rebase 代替 git pull，以避免在更新本地分支时产生不必要的合并提交。
  • 清理过时的远程引用：清理本地已删除的远程分支的引用。 
    git fetch --prune
  • 有用的别名 (Aliases)：将这些别名添加到你的 .gitconfig 文件中，可以加快工作流程。 
    [alias]
    st = status
    co = checkout
    br = branch
    lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

🎯 目标：建立高效、规范的代码协作流程