编写优秀的 Git 提交信息：清晰历史的最佳实践

Git 提交信息是当代码出错、行为改变或需要解释发布时，您的团队所依赖的笔记。一条清晰的信息能告诉您发生了什么变化以及为什么，而无需您逆向工程差异。

好的提交信息不需要花哨。它们需要一个有用的主题行、足够非平凡更改的上下文，以及您的团队在几个月后仍能阅读的一致风格。

为什么好的提交信息很重要？

好的提交信息在几个实际方面有所帮助：

• 理解更改： 它们为特定提交引入或修改的内容提供即时上下文，节省审查代码或回忆过去决策的时间。
• 调试： 在追踪错误时，清晰的提交历史允许您精确定位何时以及为何引入了有问题的更改。
• 协作： 对于加入项目或重新审视旧代码的团队成员，编写良好的信息使他们更容易理解项目的发展轨迹。
• 代码审查： 它们为审查者提供更改背后意图的洞察，促进更富有成效和专注的反馈。
• 自动化工具： 许多 Git 工具，如变更日志生成器和发布说明创建器，依赖提交信息才能有效工作。
• 历史记录： 它们作为一种文档形式，保存代码库随时间的演变。

优秀 Git 提交信息的结构

一个普遍认可的 Git 提交信息结构遵循一个简单但强大的模式：一个简洁的主题行，后跟一个可选的、更详细的主体。

主题行

主题行是提交信息的第一行。它应该是对更改的简短、祈使句总结。将其视为提交的标题。

主题行的关键指南：

• 保持简洁： 大约 50 个字符是一个有用的目标，不是硬性限制。保持主题足够短，以便在 git log --oneline 中扫描。
• 使用祈使语气： 以描述动作的动词开头，就像在发出命令一样。示例：修复、添加、重构、更新、移除、样式。
• 首字母大写： 标准惯例要求主题行的第一个字母大写。
• 不要以句号结尾： 主题行是标题，不是句子。
• 避免对较长的信息使用 git commit -m "message"： 虽然对简短注释很方便，但可能导致结构不佳的信息。使用不带参数的 git commit 打开编辑器以编写更复杂的信息。

好的主题行示例：

• feat: 添加用户认证模块
• fix: 解决数据处理中的无限循环
• docs: 更新 README 安装步骤
• refactor: 简化图片加载
• chore: 更新开发依赖

主体

提交信息的主体是您提供更多上下文和细节的地方。它通过一个空行与主题行分隔。此部分是可选的，但对于任何非平凡的更改强烈推荐。

主体的关键指南：

• 解释“为什么”和“如何”： 不要仅仅描述什么改变了；解释为什么需要更改以及如何实现。此提交解决了什么问题？以前的行为是什么？新行为是什么？
• 每行 72 个字符换行： 这是一个长期以来的惯例，可以提高许多 Git 工具和终端的可读性。
• 对列表使用项目符号： 如果需要列举多个更改或要点，使用项目符号以提高清晰度。
• 引用问题或工单： 如果提交与问题跟踪器（例如 GitHub Issues、Jira）相关，包括工单号以便追溯。

好的提交信息示例（主题 + 主体）：

feat: 实现用户个人资料页面

此提交引入了用户个人资料页面，允许用户查看和编辑他们的个人信息。

以前，用户无法访问或修改其个人资料详情。
此更改添加了一个新路由 (`/profile`) 和一个相应的组件，
该组件从 API 获取用户数据，并提供用于更新姓名、电子邮件和简介等字段的表单。

相关于 #123。

常见的提交信息类型（约定式提交）

遵循提交信息类型的约定可以进一步提高清晰度并启用自动化工具。约定式提交 规范是一个流行的标准，提倡结构化的方法。

约定式提交使用前缀来表示更改的类型：

• feat（特性）： 向代码库引入新功能。
• fix（错误修复）： 修复了一个错误。
• docs（文档）： 仅对文档的更改。
• style（格式）： 不影响代码含义的更改（空白、格式、缺少分号等）。
• refactor（重构代码）： 既不修复错误也不添加功能的代码更改。
• perf（性能）： 提高性能的代码更改。
• test（添加缺失测试或更正现有测试）： 添加或更正测试。
• build（影响构建系统或外部依赖的更改）： 示例包括 npm 脚本、webpack 等。
• ci（对 CI 配置文件和脚本的更改）： 示例包括 Travis、Circle、BrowserStack、SauceLabs 等。
• chore（维护工作）： 不适合其他类型的任务，例如仓库维护。

范围（可选）： 可以在前缀后添加一个范围，以指示受影响的代码库部分。例如：feat(auth): 添加 JWT 认证。

页脚（可选）： 使用页脚引用问题、标记破坏性更改或添加其他元数据。约定式提交使用 BREAKING CHANGE: 表示破坏性更改。

使用约定式提交的示例：

fix(api): 更正用户数据检索的端点

以前，`/users/:id/data` 端点返回过时的信息。
此提交将端点更新为 `/users/:id/profile`，该端点获取
最新的用户个人资料数据。

关闭 #456

编写优秀提交信息的技巧

• 频繁但逻辑地提交： 进行小的、原子性的提交，代表单个逻辑更改。这使信息更容易编写和理解。
• 从项目未来的角度编写信息： 想象您在六个月后回顾此提交。您需要什么信息才能快速理解更改？
• 具体化： 避免模糊的信息，如“更新代码”或“错误修复”。准确解释更新或修复了什么。
• 对代码引用使用反引号： 如果提到文件名、函数或变量名，将它们括在反引号（`）中。
• 审查您的信息： 在提交之前，花点时间阅读您的信息。它有意义吗？清晰吗？

要点

为将在审查、回滚或事件期间阅读它的每个人编写每条提交信息。使用简短的祈使句主题，当原因不明显时添加主体，并保持每次提交专注于一个逻辑更改。