本文永久链接 – https://tonybai.com/2025/04/24/conventional-commits-guide

告别混乱Commit Log！用规范指引你写出有意义的提交！

大家好，我是Tony Bai。

Git的Commit Log (提交日志) 是项目演进的脉络，也是开发者之间沟通变更、追溯历史、理解代码演变的关键载体。然而，在实际开发中，我们常常面对杂乱无章、意义不明的提交信息——”fix bug”、”update code”、”wip” 等屡见不鲜。这些模糊的记录不仅让代码审查、问题排查和版本追溯变得异常困难，也阻碍了自动化流程的实施。Conventional Commits (约定式提交) 规范提供了一套清晰、简洁的指引，旨在将每一次提交都转化为有意义、结构化的信息单元，从而显著提升 Commit Log 的价值和可利用性。

在这篇文章中，我们将探讨Conventional Commits如何作为一项关键指引，帮助开发者和团队构建更清晰、更一致、更具信息量的提交历史。

1. Commit Log的困境：为何需要指引？

缺乏明确指引的Commit Log往往会陷入以下困境：

• 信息熵高，有效信息少: 大量模糊、随意的提交信息混杂在一起，难以快速定位关键变更或理解特定提交的目的。
• 沟通效率低下: 团队成员需要花费额外时间去解读他人的提交意图，代码审查效率降低。
• 历史追溯困难: 当需要回溯某个功能或 Bug 的引入/修复历史时，无结构的日志如同大海捞针。
• 自动化阻碍: 不一致、不可预测的提交信息使得自动化生成 Changelog、语义化版本控制（SemVer）等流程难以实现。

面对这些普遍存在的困境，业界亟需一套行之有效的规范来引导开发者记录更有价值的提交信息。这正是 Conventional Commits 规范所要解决的核心问题，它通过引入一套简洁而强大的结构化指引来实现这一目标。Conventional Commits并非强制性的铁律，而是一套强大的指引 (Guidance)，它通过引入轻量级的结构化约定，引导开发者在提交时思考并明确表达变更的性质、范围和影响。

2. Conventional Commits 核心指引：结构化的力量

该规范的核心指引体现在其简洁的提交信息结构上(如下所示)：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

遵循这项指引，每次提交都应包含以下关键要素：

• Type (类型): [必须遵循的指引] 表明提交的性质。规范定义了基础类型：

  • fix:：修复 Bug (对应 SemVer PATCH)。
  • feat:：引入新功能 (对应 SemVer MINOR)。
  • 鼓励扩展: 团队可以根据需要定义其他类型，如 build, chore(用于标记那些不涉及新特性或修复的常规维护工作，比如更新依赖项等), ci, docs, style, refactor, perf, test等，以适应具体工作流。这些扩展类型本身通常不直接影响版本号（除非包含破坏性变更）。

• Scope (范围): [可选但推荐的指引] 明确提交影响的代码库区域或模块，用括号包裹，如 feat(api): 或 fix(parser):。这极大地增强了信息的可定位性。

• Description (描述): [必须遵循的指引] 紧跟冒号和空格，用简洁的语言（推荐使用祈使句现在时）概括本次提交的核心变更内容。这是提交信息的“标题”。

• Body (正文): [可选指引] 当简短描述不足以说明时，提供更详细的上下文、动机和实现细节。与 Description 之间需空一行。

• Footer(s) (脚注): [可选指引] 提供元数据，如关联 Issue (Refs: #123)。特别重要的两个脚注指引：

  • BREAKING CHANGE: ：明确标示不兼容的 API 变更 (对应 SemVer MAJOR)。
  • INITIAL STABLE RELEASE: ：标记项目从 0.y.z 进入 1.0.0。

强调重要变更的简化指引： 规范还提供了 ! (紧跟 type 或 scope 之后) 和 !! 作为标记 BREAKING CHANGE 和 INITIAL STABLE RELEASE 的快捷方式，进一步简化遵循指引的实践。

为了更直观地理解这个结构，以下是一些典型的Conventional Commits示例：

• 简单的 Bug 修复:

fix: correct minor typos in documentation

• 带范围的新功能:

feat(lang): add Polish language support

• 使用 ! 标记破坏性变更:

refactor!(auth): remove deprecated JWT authentication method

注意：这里的 ! 表明这是一个破坏性变更，即使type是refactor。

• 包含详细正文和脚注的提交:

perf(api): improve user query performance significantly

Implemented a new indexing strategy for the users table and optimized
the SQL query execution plan. Initial tests show a 50% reduction
in average query latency under heavy load.

Reviewed-by: Alice <alice@example.com>
Refs: #456, #478

• 使用 !! 标记首次稳定版发布:

chore(release)!!: prepare for 1.0.0 stable release

Finalized documentation, updated dependencies, and ran comprehensive
end-to-end tests to ensure stability for the first major release.

INITIAL STABLE RELEASE: The project is now considered stable for production use.

通过遵循这些简单的指引，原本混乱的Commit Log就被转化为结构清晰、信息丰富的记录。

理解了 Conventional Commits 的核心结构和要素后，我们自然会问：遵循这项指引究竟能为开发者和团队带来哪些实实在在的好处？答案是多方面的，它能让原本静态、难以利用的 Commit Log “活”起来，释放出巨大的潜在价值。

首先，结构化的 type 和 scope 提升了可读性与可理解性，使团队能够快速筛选和定位信息，清晰的 description 和 body 阐述了变更的“什么”和“为什么”。

其次，一致的格式增强了团队沟通与协作，减少了误解，提高了代码审查和协作效率，使每一次提交都成为清晰的沟通。

此外，结构化的日志简化了历史追溯与问题排查，便于查找特定功能引入、Bug 修复或破坏性变更的源头。

最后，一个充满有意义提交的日志自然而然地成为自动化工具的理想输入，能够驱动自动化生成 CHANGELOG、自动化 SemVer 版本判断，以及基于提交类型触发不同的 CI/CD 流程。

认识到 Conventional Commits 带来的显著价值后，如何在日常开发中有效地遵循并最大化其效益，就成了一个关键问题。仅仅了解规范的语法是不够的，掌握一些最佳实践和深入的洞察，能帮助我们更好地将这项指引融入工作流。

3. 遵循指引的最佳实践与洞察

为了更好地应用Conventional Commits指引，以下几点值得关注：

• 原子化提交: 我们鼓励将复杂的变更分解为多个逻辑上独立的、遵循单一type的提交。这本身就是一种良好的 Git 实践，很多大厂的git commit规范以及代码review规范也是这么要求的。Conventional Commits 进一步强化了这一点。

• 选择最合适的Type: 当一次提交包含多种类型的变更时（虽然应尽量避免），选择最能代表其核心意图的 type，并在 Body 中详述其他变更。

• 祈使句现在时: 推荐使用如 “Add feature”、”Fix bug” 的风格撰写 Description，简洁、直接，如同给代码库下达指令。

• 利用工具辅助: 社区提供了丰富的工具（如Commitizen, commitlint等）来帮助开发者遵循规范格式，并在提交前进行校验，降低遵循指引的负担。

• 团队共识与逐步采纳: 引入规范需要团队达成共识。可以通过分享、讨论和使用工具逐步推广。

当然，良好实践的推广离不开工具的支持。幸运的是，围绕 Conventional Commits 已经形成了一个活跃的社区和丰富的工具生态系统，它们极大地降低了开发者遵循规范的门槛，让指引更容易落地。

4. 社区生态：工具让指引落地

Conventional Commits 的流行离不开活跃的社区和丰富的工具支持，它们帮助开发者轻松地将这项指引融入日常工作流：

• Commitizen: 交互式命令行工具，引导用户创建符合规范的提交信息。
• Commitlint: 用于校验提交信息是否符合规范，常与 Git Hooks (如 husky) 集成。
• IDE 插件: 主流 IDE (VS Code, JetBrains IDEs 等) 均有插件提供模板、补全和校验支持。
• 自动化版本与 Changelog 工具: 如 semantic-release, goreleaser/chglog等，它们消费符合规范的提交历史。

这两年基于大模型的辅助生成commit log的工具以及一些代码智能体应用(如Cursor等）也在规范git commit log方面起到了非常积极的作用，对于像我这样英语非母语但又喜欢以英文log提交的选手来说，这些工具大幅降低了我在纠结如何写commit log时的心智负担，给予了我很大的帮助。

5. 小结

总而言之，Conventional Commits 远不止一套冷冰冰的格式规则，它更像是一位贴心的向导，一项旨在将每一次提交都转化为宝贵信息资产的核心指引。它赋予我们结构化的力量，能够将困扰许多团队的混乱、低效的Commit Log，转变为清晰、一致且富有洞察力的项目演进历史——这对于提升代码可维护性、团队协作效率乃至自动化流程都至关重要。

现在，就将这项指引融入你的日常开发吧！ 让每一次git commit不再是随意的记录，而是对项目演进负责任的、有意义的贡献。

那么，你的团队是如何采纳和实践提交规范的？你在使用Conventional Commits或其他规范时，有什么独到的心得或踩过的“坑”吗？

非常期待在评论区看到你的分享与交流！

如果这篇文章让你觉得“提交信息确实应该更有意义”，请分享给你的同事或团队，一起提升代码库的 Commit Log 质量吧!

别忘了关注我，持续获取更多提升研发效能的实用技巧与深度解析。

6. 参考资料

• Conventional Commits v1.0.0 – https://www.conventionalcommits.org/en/v1.0.0/#specification

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格6$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

© 2025, bigwhite. 版权所有.

本文永久链接 – https://tonybai.com/2025/03/28/go-mod-verify-tag

Go模块(module)在Go 1.11版本中引入，显著简化了依赖管理，使开发者能够通过go.mod文件明确声明和管理库依赖，支持语义版本控制，并提高了构建速度和可移植性。使得Go语言的依赖管理更加现代化和高效，提升了开发者的体验。

同时引入的校验和数据库 (sumdb) 也极大地增强了Go生态的依赖管理的确定性和安全性。然而，在模块作者发布新版本时，从本地代码库打上标签推送到代码托管平台，再到被Go Proxy和sumdb收录，这个过程中仍然存在一个微妙但关键的信任验证环节缺失。近期，Go团队接受了一项备受关注的提案(Issue #68669，旨在通过扩展go mod verify命令来弥补这一空白，为模块作者提供一种官方途径来验证他们本地的代码和标签确实与Go生态系统将收录的版本一致。在这一篇文章中，我就根据issue中的内容，来简单介绍一下这一新增安全机制的背景和运作原理。

注：该机制的提案刚刚被Accept，尚未确定在哪个版本落地，不过大概率是在Go 1.25版本中。

1. 问题背景：发布过程中的信任鸿沟

当前，Go开发者在发布一个新的模块版本时，通常的流程是：

• 在本地代码库完成开发和测试。
• 使用git tag (例如git tag v1.2.3) 创建版本标签。
• 使用git push –tags 将代码和标签推送到代码托管平台 (如 GitHub)。
• 等待Go Proxy (如proxy.golang.org) 拉取新版本，并将其信息提交给官方sumdb。

虽然sumdb保证了下游用户下载的模块代码未被篡改 (相对于sumdb中的记录)，但它无法保证sumdb中记录的版本就精确地是模块作者在本地打标签时所期望的版本。潜在的风险点包括：

• 代码托管平台被篡改: 拥有强制推送权限的攻击者可能在标签推送后修改了标签指向的提交。
• 代码托管平台自身问题: 平台自身可能存在Bug或被攻击，导致返回给Go Proxy的代码与原始标签不符。
• Go Proxy或sumdb问题: 尽管概率较低，但中间环节也可能存在问题。

正如提案贡献者和Go核心团队成员在讨论中指出的，目前缺少一个简单直接的方式让模块作者确认：“我本地标记为v1.2.3的代码，是否就是全世界通过Go工具链获取到的那个v1.2.3？”。

2. 提案核心：go mod verify -tag

为了解决这个问题，提案#68669建议为现有的go mod verify命令增加一个新的-tag标志。go mod verify命令目前用于检查本地缓存的依赖项是否被修改，而新的-tag标志则将关注点转向了当前模块本身。

2.1 拟议的功能

$go mod verify -tag=<value>

其中 可以是：

• : 一个具体的 Git 标签，例如v1.2.3。命令将检查本地仓库中该标签对应的代码树，计算其哈希，并与sumdb中记录的该版本的哈希进行比对。
• latest: 检查本地仓库中最新的Git标签。
• all: 检查本地仓库中所有的Git标签。

2.2 核心价值与使用场景

1. 发布后验证 (主要场景)：这是该提案最核心的预期用途。模块作者在推送标签后，可以立即运行此命令来确认他们的代码已经“安全”地进入了Go的模块分发体系，且内容无误。

# 假设已完成开发
$git tag v1.2.3
$git push origin v1.2.3 # 或 git push --tags

# 关键一步：验证刚推送的标签
$go mod verify -tag=v1.2.3

这个操作还有一个重要的副作用：如果v1.2.3 尚未被Go Proxy和sumdb收录，运行go mod verify -tag=v1.2.3 会触发Go工具链去查询这个版本，从而加速它被Go生态系统发现和记录的过程，同时完成验证。

1. 安全审计与代码审查: 当需要对某个模块的特定版本进行安全审计或深入的代码审查时，可以使用此命令验证本地检出的代码副本确实是sumdb中记录的那个“官方”版本，而不是可能已被篡改的某个代码托管平台上的版本。

3 社区讨论与设计考量

在提案的讨论过程中，社区也探讨了该功能是否应该放在go mod verify命令下，因为它与验证依赖项的现有功能有所不同。一些替代方案被提出，例如创建一个新的子命令go mod verify-tags或go mod proxy -check=TAG等。

最终，提案审查小组倾向于并接受了将此功能作为go mod verify的扩展，主要是考虑到：

• 概念一致性: 虽然对象不同（当前模块 vs 依赖项），但核心都是进行某种形式的“验证” (verify)。
• 避免命令扩散: 增加标志比增加新子命令更轻量。
• 文档可更新: 可以通过更新go mod verify 的文档来清晰地说明其扩展后的功能范围。

需要注意的是，该提案主要解决的是模块作者验证自身发布的问题，与验证项目依赖项是否在源头（如GitHub）被篡改（例如Issue #66653讨论的情况）是不同的问题，尽管它们都属于Go模块供应链安全的一部分。

4. 小结

go mod verify -tag提案的接受是Go模块生态系统在安全性方面迈出的又一重要步伐。它为模块作者提供了一个简单、官方的工具来关闭发布流程中的一个关键信任缺口，增强了从代码编写到模块分发的端到端完整性保证。

虽然具体的实现细节仍在进行中 (由 Issue #68669 跟踪)，但Go开发者可以期待在未来的Go版本中获得这一实用功能。这不仅有助于提升个别模块的安全性，也将进一步巩固整个Go生态系统的供应链安全基础。

5. 参考资料

• Go Issue #68669: https://github.com/golang/go/issues/68669 – https://github.com/golang/go/issues/68669
• 相关变更CL: https://go.dev/cl/596097 – https://go.dev/cl/596097

Gopher部落知识星球在2025年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。并且，2025年将在星球首发“Go陷阱与缺陷”和“Go原理课”专栏！此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格6$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

© 2025, bigwhite. 版权所有.

本文永久链接 – https://tonybai.com/2024/10/11/the-cl-author-guide-to-getting-through-code-review

Google在软件工程领域对IT界做出了卓越的贡献，从《Google软件工程》，到Google Style Guides，再到The Change Author’s Guide。这些实践参考不仅提升了软件工程的标准，也为全球IT行业的发展提供了宝贵的资源和指导。由于Go是Google开源的，其cl review基本上是遵循了Google内部的标准和实践，可以帮助开发人员更快地完成审核并获得更高质量的结果。因此在这篇文章中，我翻译一下The Change Author’s Guide，供大家参考。

The Change Author’s Guide分为三部分，由于每一部分篇幅都不多，这里就放在一起了。本次翻译是基于Google Engineering Practices Documentation的commit 3bb3ec25b3b0199f4940b1aa75f0ac5c5753301c进行的。

注：Google内部使用的术语CL代表“变更列表(changelist)”，指的是一个自包含的更改，该更改已经提交到版本控制系统或正在进行代码评审。其他组织通常称之为“变更”、“补丁”或“拉取请求(PR)”。

1. 编写良好的CL描述

CL描述是变更的公开记录，重要的是它能够传达以下信息：

• 做了什么 变更？这应该总结主要的变化，使读者在不需要阅读整个CL的情况下了解正在发生的变化。
• 为什么要做出这些变更？作为作者，你在做出这个变更时有什么背景？以及你做出的那些在源代码中无法反映出来的决策？等等。

CL描述将成为我们版本控制历史的一部分，未来可能会被数百人阅读。

未来的开发人员将根据描述搜索你的CL。未来某人可能因为对其相关性有模糊的记忆而寻找你的变更，但没有具体细节。如果所有重要信息都在代码中而非描述中，他们将更难找到你的CL。

而且，在他们找到CL后，是否能够理解为什么做出这个变更？阅读源代码可能会揭示软件在做什么，但可能不会揭示其存在的原因，这可能会使未来的开发人员更难知道他们是否可以移动切斯特顿的栅栏(Chesterton’s fence)。

译注：切斯特顿的栅栏是一种启发式方法，由G.K.切斯特顿提出，旨在告诫人们在改变任何系统之前，应先了解该系统存在的原因和功能，否则可能会造成更大的问题。

一个编写良好的CL描述将帮助这些未来的工程师——有时，也包括你自己！

1.1 第一行(first line)

• 简短总结所做的内容。
• 使用完整句子，以命令的形式书写。
• 后面跟一个空行。

CL描述的第一行应该是对具体做了什么的简短总结，后面跟一个空行。这是出现在版本控制历史摘要中的内容，因此应该提供足够的信息，使未来的代码搜索者无需阅读你的CL或其整个描述就能理解你的CL实际上做了什么，或与其他CL的不同之处。也就是说，第一行应该独立存在，让读者更快地浏览代码历史。

尽量保持第一行简短、重点突出且切中要点。清晰性和对读者的实用性应是最重要的。

按照传统，CL描述的第一行应该是一个完整的句子，并以命令形式书写（即祈使句）。例如，应该说“Delete the FizzBuzz RPC and replace it with the new system.”，而不是“Deleting the FizzBuzz RPC and replacing it with the new system.”，不过，你不必将其余的描述写成祈使句。

1.2 主体信息要丰富

第一行应该是简短且重点突出的摘要，而其余的描述应详细说明并包括读者理解变更列表所需的任何补充信息。它可能包括对正在解决的问题的简要描述，以及为什么这是最佳方法。如果该方法有任何不足之处，应该指出。如果有相关信息也要列出，包含背景信息，如错误编号、基准测试结果和设计文档链接等。

如果你包含外部资源的链接，请考虑由于访问限制或保留政策，未来读者可能无法看到这些链接。在可能的情况下，包含足够的上下文，以便审查者和未来读者理解CL。

即使是小的CL也值得关注细节。将CL放在上下文中。

1.3 不好的CL描述

“Fix bug”是一个不充分的CL描述。什么bug？你做了什么来修复它？其他类似的不好的描述包括：

• “Fix build.”
• “Add patch.”
• “Moving code from A to B.”
• “Phase 1.”
• “Add convenience functions.”
• “kill weird URLs.”

其中一些都是取自真实的CL描述。虽然简短，但它们没有提供足够的有用信息。

1.4 良好的CL描述

以下是一些好的CL描述示例。

1.4.1 功能变更

示例：

RPC: Remove size limit on RPC server message freelist.

Servers like FizzBuzz have very large messages and would benefit from reuse. Make the freelist larger, and add a goroutine that frees the freelist entries slowly over time, so that idle servers eventually release all freelist entries.

第一行描述了CL实际做了什么。其余的描述谈论了正在解决的问题、为什么这是一个好的解决方案以及有关具体实现的更多信息。

1.4.2 重构

示例：

Construct a Task with a TimeKeeper to use its TimeStr and Now methods.

Add a Now method to Task, so the borglet() getter method can be removed (which was only used by OOMCandidate to call borglet's Now method). This replaces the methods on Borglet that delegate to a TimeKeeper.

Allowing Tasks to supply Now is a step toward eliminating the dependency on Borglet. Eventually, collaborators that depend on getting Now from the Task should be changed to use a TimeKeeper directly, but this has been an accommodation to refactoring in small steps.

Continuing the long-range goal of refactoring the Borglet Hierarchy.

第一行描述了CL做了什么以及这是如何与过去不同的。其余的描述谈论了具体实现、CL的背景、解决方案并不理想以及可能的未来方向。它还解释了为什么这个变更被做出。

1.4.3 需要一些上下文的小CL

示例：

Create a Python3 build rule for status.py.

This allows consumers who are already using this as in Python3 to depend on a rule that is next to the original status build rule instead of somewhere in their own tree. It encourages new consumers to use Python3 if they can, instead of Python2, and significantly simplifies some automated build file refactoring tools being worked on currently.

第一句描述了实际的变更。其余的描述解释了为什么这个变更被做出，并给审查者提供了大量的上下文信息。

1.5 使用标签(tags)

标签是手动输入的label，可用于对CL进行分类。这些标签可能由工具支持，也可能只是团队惯例。

例如：

• “[tag]“
• “[a longer tag]“
• “#tag”
• “tag:”

使用标签是可选的。

添加标签时，考虑它们是否应该在CL描述的主体中或第一行中。限制在第一行中使用标签的数量，因为这可能会模糊内容。

以下是带标签和不带标签的示例：

// Tags are okay in the first line if kept short.
[banana] Peel the banana before eating.

// Tags can be inlined in content.
Peel the #banana before eating.

// Tags are optional.
Peel the banana before eating.

// Multiple tags are acceptable if kept short.
#banana #apple: Assemble a fruit basket.

// Tags can go anywhere in the CL description.
> Assemble a fruit basket.
>
> #banana #apple

// Too many tags (or tags that are too long) overwhelm the first line.
//
// Instead, consider whether the tags can be moved into the description body
// and/or shortened.
[banana peeler factory factory][apple picking service] Assemble a fruit basket.

1.6 生成的CL描述

有些CL是由工具生成的。只要有可能，它们的描述也应该遵循此处的建议。也就是说，它们的第一行应该简短、重点突出且独立，CL描述主体应包含有助于审查者和未来代码搜索者理解每个CL效果的信息细节。

1.7 提交CL前审查描述

CL在审查过程中可能会发生重大变化。在提交CL前审查CL描述是值得的，可以确保描述仍然真实反映CL的内容。

2. 小型CL

2.1 为什么要写小型的CL？

小而简单的CL有以下优点：

• 审查速度更快。审查者更容易找到几分钟的时间来审查小CL，而不是腾出30分钟的时间来审查一个大CL。
• 审查更彻底。 对于大变更，审查者和作者往往会因大量详细评论反复交换而感到沮丧，有时甚至会错过或忽略重要点。
• 引入错误的可能性更小。由于你所做的更改较少，因此你和审查者更容易有效地推理CL的影响，并查看是否引入了错误。
• 被拒绝时浪费的工作更少。 如果你写了一个巨大的CL，然后审查者表示整体方向错误，你就浪费了很多工作。
• 更容易合并。 处理一个大CL需要很长时间，因此在合并时会遇到许多冲突，你将不得不频繁合并。
• 更容易设计良好。 完善小变更的设计和代码质量要比完善大变更的所有细节容易得多。
• 审查阻塞更少。 发送自包含的整体变更部分允许你在等待当前CL审查时继续编码。
• 回滚更简单。 大CL更可能涉及在初始CL提交和回滚CL之间更新的文件，从而增加回滚的复杂性（中间的CL可能也需要回滚）。

请注意，审查者有权仅因为变更过大而直接拒绝你的变更。通常，他们会感谢你的贡献，但会要求你以某种方式将其拆分为一系列较小的变更。在你已经编写完变更后拆分它可能会花费很多时间，或者需要大量时间来争论审查者为什么应该接受你的大变更。因此，最好一开始就写小型CL。

2.2 多小算小？

一般而言，CL的合适大小是一个自包含的变更。这意味着：

• CL进行最小变更，只解决一件事。这通常只是一个功能的一部分，而不是一次性完成整个功能。一般来说，最好宁可编写太小的CL，也不要编写太大的CL。与你的审核者合作找出可接受的尺寸。
• CL应该包含相关的测试代码。
• 审查者理解CL所需的一切（除未来开发外）都应包含在CL中，比如本CL的描述、现有代码库或他们已经审查过的CL。
• 系统在CL被检查入库后仍能良好工作，适用于其用户和开发人员。
• CL不应小到其含义难以理解。如果你添加了一个新的API，应该在同一个CL中包含对该API的使用方法，以便审查者更好地理解API将如何使用。这也能防止未使用的API被提交。

没有关于“过大”的硬性规则。100行通常是合理的CL大小，而1000行通常被认为过大，但这取决于审查者的判断。变更涉及的文件数量也会影响其“大小”。在一个文件中的200行变更可能是可以接受的，但变更分布在50个文件中的话通常会被认为过大。

请记住，尽管你从开始编写代码的那一刻起就与代码密切相关，审查者通常没有上下文。对你来说合适大小的CL可能对审查者来说会是难以接受的。若有疑问，写比你认为需要的更小的CL。审查者很少抱怨收到的CL太小。

2.3 大型CL什么时候可以？

在某些情况下，大变更并不那么糟糕：

• 通常可以将删除整个文件视为仅一行变更，因为审查者审核它所花费的时间很少。
• 有时，大CL是由你完全信任的自动重构工具生成的，审查者的工作只是验证并确认他们确实想要这个变更。这些CL可以更大，尽管上述一些注意事项（例如合并和测试）仍然适用。

2.4 高效地编写小型CL

如果你编写了一个小型CL，然后等待审查者批准它，再写下一个CL，那么你将浪费很多时间。因此，你需要找到一种方法，在等待审查时不会阻塞自己。这可能涉及同时处理多个项目，找到愿意立即可用的审查者，进行面对面审查，进行配对编程，或者以某种方式拆分你的CL，以便你能够立即继续工作。

2.5 拆分CL

如果存在多个相互依赖的CL时，我们通常有必要在深入编码之前从高层次考虑如何拆分和组织这些CL。

除了使你作为作者更容易管理和组织CL外，这也让你的代码审查者更容易，从而使你的代码审查更高效。

以下是将工作拆分为不同CL的一些策略。

2.5.1 将多个变更堆叠在一起

拆分CL的一种方法是编写一个小CL，发送审查，然后立即开始编写一个基于第一个CL的另一个CL。大多数版本控制系统都允许你以某种方式做到这一点。

2.5.2 按文件拆分

另一种拆分CL的方法是按文件分组，这些文件需要不同的审查者，但其他方面是自包含的变更。

例如：你发送一个CL用于对protocol buffer修改，另一个CL用于对使用该proto的代码的更改。你必须在code CL之前提交proto CL，但它们可以同时接受审查。如果这样做，你可能想通知两组审查者你编写的另一个CL，以便他们了解你的变更的上下文。

另一个例子：你发送一个CL用于代码变更，另一个用于使用该代码的配置或实验；如果有必要，这也更容易回滚，因为配置/实验文件有时比代码变更更快地推送到生产环境。

2.5.3 横向拆分

考虑创建共享代码或存根，以帮助隔离技术栈各层之间的变更。这不仅有助于加快开发速度，还鼓励层之间的抽象。

例如：你创建了一个计算器应用程序，其中有客户端、API、服务和数据模型层。共享的proto signature可以将服务层和数据模型层相互抽象。类似地，API存根可以将客户端代码的实现与服务代码分开，使它们能够独立演进。类似的思路也可以应用于更细粒度的函数或类级别的抽象。

2.5.4 纵向拆分

与分层的横向方法相对应，你可以将代码拆分为更小、全栈、垂直的功能。这些功能中的每一个都可以独立并行实现。这使得一些轨道能够继续前进，而其他轨道则在等待审查或反馈。

回到我们在横向拆分所举的计算器示例。你现在想支持新的运算符，如乘法和除法。你可以通过将乘法和除法实现为独立的纵向特性或子功能来拆分，尽管它们可能有一些重叠，例如共享按钮样式或共享验证逻辑。

2.5.5 横向和纵向拆分

为了进一步发展，你可以结合这些方法并制定一个实施计划，其中每个单元都是独立的CL。从模型（底部）开始，逐渐推进到客户端：

2.6 将重构与功能变更分开

通常最好将重构与功能变更或错误修复分开。例如，移动和重命名一个类应该与修复该类中的错误放在不同的CL中。这样，审查者更容易理解每个CL引入的变更。

不过，小的清理工作，例如修复局部变量名称，可以包含在功能变更或错误修复CL中。开发人员和审查者需判断何时重构的规模过大，以至于将其包含在当前CL中会使审查更加困难。

2.7 将相关的测试代码放在同一个CL中

CL应该包括相关的测试代码。请记住，这里的“小”指的是CL应该聚焦且不是单纯的行数问题。

所有谷歌的变更都需要测试。

添加或更改逻辑的CL应该伴随新的或更新的测试，以验证新行为。纯重构CL（不打算改变行为）也应有测试覆盖；理想情况下，这些测试已经存在，但如果没有，你应添加它们。

独立的测试修改可以先放入单独的CL，类似于重构准则。这包括：

• 用新测试验证预先存在的提交代码。

确保重要逻辑被测试覆盖。增加对受影响代码后续重构的信心。例如，如果你想重构没有测试覆盖的代码，提交测试CL可以在提交重构CL之前可以验证受测行为在重构前后是否保持不变。

• 重构测试代码（例如，引入助手函数）。
• 引入更大的测试框架代码（例如，集成测试）。

2.8 不要破坏构建

如果你有多个相互依赖的CL，你需要找到一种方法，在每个CL提交后确保整个系统保持正常工作。否则，你可能会在CL提交之间破坏所有同事的构建，影响大家几分钟（或在稍后的CL提交中出现意外问题时，甚至更长时间）。

2.9 无法做到足够小

有时你会遇到CL必须很大的情况。这种情况很少发生。练习编写小CL的作者几乎总能找到将功能分解为一系列小变更的方法。

在编写大CL之前，请考虑是否可以先进行仅重构的CL，以便为更干净的实现铺平道路。与你的团队成员交谈，看看是否有人对如何将功能实现为小CL发表看法。

如果所有这些选项都失败（这应该非常少见），那么请提前获得审查者的同意，以审核大CL，以便他们对即将到来的内容有所警觉。在这种情况下，预计审查过程会比较漫长，要警惕不要引入错误，并更加细致地编写测试。

3. 如何处理审查者的意见

当你将代码提交（CL）发送审查时，审查者可能会对你的代码提出多个意见。以下是一些处理审查者意见的有用建议。

3.1 不要把它视为针对个人

审查的目标是维护我们的代码库和产品的质量。当审查者对你的代码提出批评时，请将其视为他们试图帮助你、代码库和谷歌的一种方式，而不是对你或你能力的个人攻击。

有时，审查者可能会感到沮丧，并在评论中表达这种沮丧。虽然对于审查者来说，这不是一个好的做法，但作为开发人员，你应该对此有所准备。问问问自己：“审查者想要向我传达的建设性意见是什么？”然后按照他们实际所说的那样进行操作。

绝不要对代码审查意见做出愤怒的回应。 这是一种严重违反职业礼仪的行为，将在代码审查工具中留下永久记录。如果你太愤怒或烦恼而无法友好地回应，请离开电脑一段时间，或做些其他事情，直到你冷静下来再礼貌地回复。

一般来说，如果审查者没有以建设性和礼貌的方式提供反馈，请当面与他们解释。如果无法面对面或视频通话，那么可以私下发一封邮件给他们。以友好的方式解释你不喜欢的地方以及希望他们做出怎样的改变。如果他们在这次私人讨论中以非建设性的方式回应，或者没有达到预期效果，请酌情上报给你的经理。

3.2 修正代码

如果审查者表示他们不理解你代码中的某些内容，你的第一反应应该是澄清代码本身。如果代码无法澄清，请添加代码注释，解释代码存在的原因。如果某个注释似乎没有意义，你再在代码审查工具中做解释。

如果审查者不理解你的某段代码，未来其他读者也可能无法理解。写一条在代码审查工具中的回应并不能帮助未来的代码读者，但澄清代码或添加代码注释则能帮助他们。

3.3 协作思考

编写代码变更（CL）可能需要大量工作。最终将其发送审查，感觉一切都完成了，可能会很令人满意，但收到要求更改的评论时也可能会感到沮丧，尤其是当你不同意这些评论时。

在这样的时刻，请花点时间退后一步，考虑审查者是否提供了有价值的反馈，能帮助代码库和谷歌。你首先要问自己，“我理解审查者所要求的吗？”

如果你无法回答这个问题，请向审查者寻求澄清。

然后，如果你理解评论但不同意，重要的是要协作思考，而不是对抗性或防御性思考：

Bad: “No, I’m not going to do that.”

Good: "I went with X because of [these pros/cons] with [these tradeoffs]
My understanding is that using Y would be worse because of [these reasons].
Are you suggesting that Y better serves the original tradeoffs, that we should
weigh the tradeoffs differently, or something else?"

请记住，礼貌和尊重始终应放在首位。如果你不同意审查者的观点，请寻找协作的方式：寻求澄清、讨论优缺点，并解释为什么你处理事情的方法更适合代码库、用户和/或谷歌。

有时，你可能知道一些审查者不知道的关于用户、代码库或CL的信息。在适当的地方修复代码，并与审查者进行讨论，提供更多上下文。通常，你可以根据技术事实与审查者达成某种共识。

3.4 解决冲突

解决冲突的第一步始终是尝试与审查者达成共识。如果无法达成共识，请参阅代码审查标准，其中提供了在这种情况下应遵循的原则。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

© 2024, bigwhite. 版权所有.

git是那个“爱骂人”的Linux之父Linus Torvalds继Linux内核后奉献给全世界程序员的第二个礼物（不能确定已经逐渐老去的Torvalds能否迸发第三春，第三次给我们一个超大惊喜^_^）。这里再强调一下，git读作/git/，而不是/dʒit/。

在诞生十余载后(2005年发布第一版)，git毫无争议地成为了程序员版本管理工具的首选，它改变了全世界程序员的代码版本管理和生产协作的模式，极大促进了开源软件运动的发展。进化到今天的git已经成为了一个比较复杂的工具，多数程序员都将目光聚焦在如何记住这些命令并用好这些命令，对这些复杂命令行背后的原理却知之不多，虽然大多数程序员的确不太需要深刻了解git背后的原理^_^。

关于git原理的文章在互联网上也呈现出“汗牛充栋”之势，有些文章“蜻蜓点水”，有些文章“事无巨细”，看后似乎都无法让我满意。结合自己对git原理的学习，我觉得多数人把握住git运作机制的几个关键概念即可，于是就有了这篇文章，我努力尝试给大家讲清楚。

一. 我就是仓库，我拥有全部

我们首先要明确一个git与先前的版本管理工具（主要是subversion）的不同。下面是使用subversion版本管理工具时，程序员进行代码生产以及程序员间围绕代码仓库进行协作的模式：

众所周知，subversion是基于中心版本仓库进行版本管理协作的版本管理工具。就像上图中那样，所有开发人员开始生产代码的前提是必须先从中心仓库checkout一份代码拷贝到自己本地的工作目录；而进行版本管理操作或者与他人进行协作的前提也是：中心版本仓库必须始终可用。这有点像以太网的“半双工的集线器(hub)模式”：svn中心仓库就像集线器本身，每个程序员节点就像连接到集线器上的主机；当一个程序员提交(commit)代码到中心仓库时，其他程序员不能提交，否则会出现冲突；如果中心仓库挂掉了，那么整个版本管理过程也将停止，程序员节点间无法进行协作，这就像集线器(hub)挂掉后，所有连接到hub上的主机节点间的网络也就断开无法相互通信一样。

如果我们使用git，我们是不需要“集线器”的：

如上图所示，git号称分布式版本管理系统，本质上是没有像subversion中那个所谓的“中心仓库”的。每个程序员都拥有一个本地git仓库，而不仅仅是一份代码拷贝，这个仓库就是一个独立的版本管理节点，它拥有程序员进行代码生产、版本管理、与其他程序员协作的全部信息。即便在一台没有网络连接的机器上，程序员也能利用该仓库完成代码生产和版本管理工作。在网络ready的情况下，任意两个git仓库之间可以进行点对点的协作，这种协作无需中间协调者(中心仓库)参与。

二. github实现了基于git网络协作的控制平面

git实现了分布式版本管理系统，每个git仓库节点都是自治的。诸多git仓库节点一起形成了一个分布式git版本管理网络。这样的一个分布式网络存在着与普通分布式系统的类似的问题：如何发现对端节点的git仓库、如何管理和控制仓库间的访问权限等。如果说linus的git本身是这个分布式网络的数据平面工具(实现client/server间的双向数据通信)，那么这个分布式网络还缺少一个“控制平面”。

而github恰恰给出了一份git分布式网络控制平面的实现：托管、发现、控制…。其名称中含有的“hub”字样让我们想起了上面的“hub模式”：

我们看到在github的git协作模式实践中，引入了“中心仓库”的概念，各个程序员的节点git仓库源于(clone于)中心仓库。但是它和subversion的“中心仓库”有着本质的不同，这个仓库只是一个“upstream”库、是一个权威库。它并不是“集线器”，也没有按照“集线器”的那种工作模式进行协作。所有程序员节点的代码生产和版本管理操作完全可以脱离该所谓“中心库”而独立实施。

三. objects是个筐，什么都往里面装

上面都是从“宏观”谈git的一些与众不同的理念，而git原理，其实是从这一节才真正开始的^_^。

我们知道：每个git仓库的所有数据都存储在仓库顶层路径下的.git目录下：

$tree -L 1 -F
.
├── COMMIT_EDITMSG
├── HEAD
├── config
├── description
├── hooks/
├── index
├── info/
├── logs/
├── objects/
└── refs/

5 directories, 5 files

而在这些目录和文件中，又以objects路径下的数据内容最多，也最为重要。在git的设计中，objects目录就是一个“筐”，git的核心对象(object)都往里面“装”。

从上图中，我们看到objects中存储的最主要的有三类对象：blob、commit和tree。这时你可能还不知道它们究竟是啥。不过没关系，我们通过一个例子来做一下“对号入座”。

我们在一个目录下建立git-internal-repo-demo目录，进入该目录，执行下面命令创建一个git仓库：

➜  /Users/tonybai/test/git/git-internal-repo-demo git:(master) ✗ $git init .
Initialized empty Git repository in /Users/tonybai/Test/git/git-internal-repo-demo/.git/

这是一个处于初始状态的git仓库，我们看看存储git仓库数据的.git目录下的结构：

➜  /Users/tonybai/test/git/git-internal-repo-demo git:(master) $tree .git
.git
├── HEAD
├── config
├── description
├── hooks
│   ├── applypatch-msg.sample
│   ├── commit-msg.sample
│   ├── fsmonitor-watchman.sample
│   ├── post-update.sample
│   ├── pre-applypatch.sample
│   ├── pre-commit.sample
│   ├── pre-push.sample
│   ├── pre-rebase.sample
│   ├── pre-receive.sample
│   ├── prepare-commit-msg.sample
│   └── update.sample
├── info
│   └── exclude
├── objects
│   ├── info
│   └── pack
└── refs
    ├── heads
    └── tags

8 directories, 15 files

这个时候，objects这个筐还是空的！我们这就为仓库添点内容：

$mkdir -p cmd/demo

在cmd/demo目录下添加main.go文件，内容如下:

// cmd/demo/main.go
package main

import "fmt"

func main() {
    fmt.Println("hello, git")
}

接下来我们使用git add将cmd/demo目录加入到stage区：

$git add .

$git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

    new file:   cmd/demo/main.go

这时我们来看一下objects这个筐是否有变化：

├── objects
│   ├── 3e
│   │   └── 759ef88951df9b9b07077a7ec01f96b8e659b3
│   ├── info
│   └── pack

我们有一个object已经被装入到“筐”中了。我们看到objects目录下是一些以哈希值命名的文件和目录，其中目录由两个字符组成，是每个object hash值的前两个字符。hash值后续的字符串用于命名对应的object文件。在这里我们的object的hash值(实质是sha-1算法)为3e759ef88951df9b9b07077a7ec01f96b8e659b3，于是这个对象就被放入名为3e的目录下，对应的object文件为759ef88951df9b9b07077a7ec01f96b8e659b3。

我们使用git提供的低级命令查看一下这个object究竟是什么，其中git cat-file -t查看object的类型，git cat-file -p查看object的内容：

$git cat-file -t 3e759ef889
blob

$git cat-file -p 3e759ef889
package main

import "fmt"

func main() {
    fmt.Println("hello, git")
}

我们看到objects这个筐中多了一个blob类型的对象，对象内容就是前面main.go文件中内容。

接下来，我们提交一下这次变更：

$git commit -m"first commit" .
[master (root-commit) 3062e0e] first commit
 1 file changed, 7 insertions(+)
 create mode 100644 cmd/demo/main.go

再来看看.git/objects中的变化：

├── objects
│   ├── 1f
│   │   └── 51fe448aacc69c0f799def9506e61ed3eb60fa
│   ├── 30
│   │   └── 62e0ebad9415b704e96e5cee1542187b7ed571
│   ├── 3d
│   │   └── 2045367ea40c098ec5c7688119d72d97fb09a5
│   ├── 3e
│   │   └── 759ef88951df9b9b07077a7ec01f96b8e659b3
│   ├── 40
│   │   └── 6d08e1159e03ae82bcdbe1ad9f076a04a41e2b
│   ├── info
│   └── pack

我们看到筐里被一下子新塞入4个object。我们分别看看新增的4个object类型和内容都是什么：

$git cat-file -t 1f51fe448a
tree
$git cat-file -p 1f51fe448a
100644 blob 3e759ef88951df9b9b07077a7ec01f96b8e659b3    main.go

$git cat-file -t 3062e0ebad
commit
$git cat-file -p 3062e0ebad
tree 406d08e1159e03ae82bcdbe1ad9f076a04a41e2b
author Tony Bai <bigwhite.cn@aliyun.com> 1586243612 +0800
committer Tony Bai <bigwhite.cn@aliyun.com> 1586243612 +0800

first commit

$git cat-file -t 3d2045367e
tree
$git cat-file -p 3d2045367e
040000 tree 1f51fe448aacc69c0f799def9506e61ed3eb60fa    demo

$git cat-file -t 406d08e115
tree
$git cat-file -p 406d08e115
040000 tree 3d2045367ea40c098ec5c7688119d72d97fb09a5    cmd

这里我们看到了另外两种类型的object被加入“筐”中：commit和tree类型。objects这个筐里目前有了5个object，我们不考虑git是以何种格式存储这些object的，我们想知道的是这几个object的关系是什么样的。请看下一小节^_^。

四. 每个commit都是一个git仓库的快照

要理清objects“筐”中各object间的关系，就必须要把握住一个关键概念：“每个commit都是git仓库的一个快照” – 以一个commit为入口，我们能将当时objects下面的所有object联系在一起。因此，上面5个object中的那个commit对象就是我们分析各object关系的入口。我们根据上述5个object的内容将这5个object的关系组织为下面这幅示意图：

通过上图我们看到：

• commit是对象关系图的入口；

• tree对象用于描述目录结构，每个目录节点都会用一个tree对象表示。目录间、目录文件间的层次关系会在tree对象的内容中体现；

• 每个commit都会有一个root tree对象；

• blob对象为tree的叶子节点，它的内容即为文件的内容。

上面仅是一次commit后的关系图，为了更清晰的看到多个commit对象之间关系，我们再来对git repo进行一次变更提交:

我们创建pkg/foo目录：

$mkdir -p pkg/foo

然后创建文件pkg/foo/foo.go，其内容如下：

// pkg/foo/foo.go
package foo

import "fmt"

func Foo() {
    fmt.Println("this is foo package")
}

提交这次变更：

$git add pkg
$git commit -m"add package foo" .
[master 6f7f08b] add package foo
 1 file changed, 7 insertions(+)
 create mode 100644 pkg/foo/foo.go

下面是提交变更后的“筐”内的对象：

$tree objects
objects
├── 1f
│   └── 51fe448aacc69c0f799def9506e61ed3eb60fa
├── 29
│   └── 3ae375dcef1952c88f35dd4d2a1d4576dea8ba
├── 30
│   └── 62e0ebad9415b704e96e5cee1542187b7ed571
├── 3d
│   └── 2045367ea40c098ec5c7688119d72d97fb09a5
├── 3e
│   └── 759ef88951df9b9b07077a7ec01f96b8e659b3
├── 40
│   └── 6d08e1159e03ae82bcdbe1ad9f076a04a41e2b
├── 65
│   └── 5dd3aae645813dc53834ebfa8d19608c4b3905
├── 6e
│   └── e873d9c7ca19c7fe609c9e1a963df8d000282b
├── 6f
│   └── 7f08b14168beb114c3cc099b8dc1c09ccd4739
├── cc
│   └── 9903a33cb99ae02a9cb648bcf4a71815be3474
├── info
└── pack

12 directories, 10 files

object已经多到不便逐一分析了。但我们把握住一点：commit是分析关系的入口。我们通过commit的输出或commit log(git log)可知，新增的commit对象的hash值为6f7f08b141。我们还是以它为入口分析新增object的关系以及它们与之前已存在的object的关系：

从上图我们看到：

• git新创建tree对象对应我们新建的pkg目录以及其子目录；

• cmd目录下的子目录和文件内容并未改变，因此这次commit所对应的root tree对象(293ae375dc)直接使用了已存在的cmd目录对应的对象(3d2045367e);

• 新commit对象会将第一个commit对象作为parent，这样多个commit对象之间构成一个单向链表。

上面的两个提交都是新增内容，我们再来提交一个commit，这次我们对已有文件内容做变更：

将cmd/demo/main.go文件内容变更为如下内容：

// cmd/demo/main.go
package main

import (
    "fmt"

    "github.com/bigwhite/foo"
)

func main() {
    fmt.Println("hello, git")
    foo.Foo()
}

提交变更：

$git commit -m"call foo.Foo in main" .
[master 2f14635] call foo.Foo in main
 1 file changed, 6 insertions(+), 1 deletion(-)

和上面的分析方法一样，我们通过最新commit对应的hash值2f146359b4对新对象和现存对象的关系进行分析：

如上图，第三次变更提交后，我们看到：

• 由于main.go文件变更，git重建了main.go blob对象、demo、cmd tree对象

• 由于pkg目录、其子目录布局、子目录下文件内容没有改变，于是新commit对象对应的root tree对象直接“复用”了上一次commit的pkg tree对象。

• 新commit对象加入commit对象单向链表，并将上一次的commit对象作为parent。

我们看到沿着最新的commit对象(2f146359b4)，我们能获取当前仓库的最新结构布局以及各个blob对象的最新内容，即最新的一个快照！

五. object是不可变的，默克尔树(Merkle Tree)判断变化

从上面的三次变更，我们看到无论哪种对象object，一旦放入到objects这个“筐”就是不可变的(immutable)。即便是第三次commit对main.go进行了修改，git也只是根据main.go的最新内容创建一个新的blob对象，而不是修改或替换掉第一版main.go对应的blob对象。

对应目录的tree object亦是如此。如果某目录下的二级目录发生变化或目录下的文件内容发生改变，git会新生成一个对应该目录的tree对象，而不是去修改原先已存在的tree对象。

实际上，git tree对象的组织本身就是一棵默克尔树(Merkle Tree)。

默克尔树是一类基于哈希值的二叉树或多叉树，其叶子节点上的值通常为数据块的哈希值，而非叶子节点上的值，是将该节点的所有孩子节点的组合结果的哈希值。默克尔树的特点是，底层数据的任何变动，都会传递到其父亲节点，一直到树根。

以上图为例：我们自下向上看，D0、D1、D2和D3是叶子节点包含的数据。N0、N1、N2和N3是叶子节点，它们是将数据（也就是D0、D1、D2和D3）进行hash运算后得到的hash值；继续往上看，N4和N5是中间节点，N4是N0和N1经过hash运算得到的哈希值，N5是N2和N3经过hash运算得到的哈希值。（注意，hash值计算方法：把相邻的两个叶子结点合并成一个字符串，然后运算这个字符串的哈希）。最后，Root节点是N4和N5经过hash运算后得到的哈希值，这就是这颗默克尔树的根哈希。当N0包含的数据发生变化时，根据默克尔树的节点hash值形成机制，我们可以快速判断出：N0、N4和root节点会发生变化。

对应git来说，叶子节点对应的就是每个文件的hash值，tree对象对应的是中间节点。因此，通过默克尔树(Merkle Tree)的特性，我们可以快速判断哪些对象对应的目录或文件发生了变化，应该重新创建对应的object。我们还以上面的第三次commit为例：

六. branch和tag之所以轻量，因为它们都是“指针”

使用subversion时，创建branch或打tag使用的是svn copy命令。svn copy执行的就是真实的文件拷贝，相当于将trunk下的目录和文件copy一份放到branch或tag下面，建立一个trunk的副本，这样的操作绝对是“超重量级”的。如果svn仓库中的文件数量庞大且size很大，那么svn copy执行起来不仅速度慢，而且还会在svn server上占用较大的磁盘存储空间，因此使用svn时，打tag和创建branch是要“谨慎”的。

而git的branch和tag则极为轻量，我们来给上面例子中的仓库创建一个dev分支：

$git branch dev

我们看看.git下有啥变化：

.

└── refs
    ├── heads
    │   ├── dev
    │   └── master
    └── tags

我们看到.git/refs/heads下面多出了一个dev文件，我们查看一下该文件的内容：

$cat refs/heads/dev
2f146359b475909f2fdcdef046af3431c8077282

$git log --oneline

2f14635 (HEAD -> master, dev) call foo.Foo in main
6f7f08b add package foo
3062e0e first commit

对比发现，dev文件中的内容恰是最新的commit对象：2f146359b475909f2fdcdef046af3431c8077282。

我们再来给repo打一个tag：

$git tag v0.0.1

同样，我们来查看一下.git目录下的变化：

└── refs
    ├── heads
    │   ├── dev
    │   └── master
    └── tags
        └── v0.0.1

我们看到在refs/tags下面增加一个名为v0.0.1的文件，查看其内容：

$cat refs/tags/v0.0.1
2f146359b475909f2fdcdef046af3431c8077282

和dev分支文件一样，它的内容也是最新的commit对象：2f146359b475909f2fdcdef046af3431c8077282。

可见，使用git创建分支或tag仅仅是创建了一个指向某个commit对象的“指针”，这与subversion的副本操作相比，简直不能再轻量了。

前面说过，一个commit对象都是一个git仓库的快照，切换到(git checkout xxx)某个branch或tag，就是将本地工作拷贝切换到commit对象所代表的仓库快照的状态。当然也会将commit对象组成的单向链表的head指向该commit对象，这个head即.git/HEAD文件的内容。

七. 小结

到这里，git原理的几个关键概念就交代完了，再回顾一下：

• 和subversion这样的集中式版本管理工具最大的不同就是每个程序员节点都是git仓库，拥有全部开发、协作所需的全部信息，完全可以脱离“中心节点”；

• 如果说git聚焦于数据平面的功能，那么github则是一个基于git网络协作的控制平面的实现；

• objects是个筐，什么都往里面装。git仓库的核心数据都存在.git/objects下面，主要类型包括：blob、tree和commit；

• 每个commit都是一个git仓库的快照，记住commit对象是分析对象关系的入口;

• git是基于数据内容的hash值做等值判定的，object是不可变的，默克尔树(Merkle Tree)用来快速判断变化。

• branch和tag因为是“指针”，因此创建、销毁和切换都非常轻量。

八. 参考资料

• Pro Git v2 – https://git-scm.com/book/en/v2

• git介绍 – https://www.cnblogs.com/kisun168/p/11408346.html

• git内部原理 – https://zhuanlan.zhihu.com/p/53750883

• git仓库内部结构 – https://www.jianshu.com/p/72f9f8c9c47e

我的网课“Kubernetes实战：高可用集群搭建、配置、运维与应用”在慕课网上线了，感谢小伙伴们学习支持！

我爱发短信：企业级短信平台定制开发专家 https://tonybai.com/
smspush : 可部署在企业内部的定制化短信平台，三网覆盖，不惧大并发接入，可定制扩展； 短信内容你来定，不再受约束, 接口丰富，支持长短信，签名可选。

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

微博：https://weibo.com/bigwhite20xx
微信公众号：iamtonybai
博客：tonybai.com
github: https://github.com/bigwhite

微信赞赏：

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

© 2020, bigwhite. 版权所有.

一、Commit Context

今日的软件复杂度日益增加，软件开发模式也早已从单打独斗的英雄模式变成了团队协作模式了，而在团队模式下，版本控制系统发挥着至关重要的作用， 它让开发过程变得有序，将冲突解决的成本尽可能地降低到最低。但版本控制系统毕竟不是智能的，它只是机械地记录着每次提交前后的内容的raw差 异，至于这个差异究竟代表了什么，版本管理系统是不得而知的，这就需要我们开发者们来提供，这就算是产生commit context的动机吧。即便是一个人开发维护的项目，个人的记忆也是有时效性的，时间久了，以前的代码变更context势必也就淡忘了，良好且规范的 commit context有助于更好的维护项目，追踪历史思路和行为，甚至在查找bug时也是能帮得上大忙的，比如确认bug引入的时段边界、代码范围等。

前面说了，commit context最终是以commit log形式提供的，这才是我在这篇文章中真正要说的内容^_^。评价一个项目的好坏，无论是商业项目，还是开源项目，代码本身质量是一个重要的方面，代码 维护的规范性则是另外不可忽略的一个重要因素，而在代码维护规范性方面，commit log的规范是一项重要内容。做了这么多年Coding工作，到目前为止部门内部还没有哪一个项目在commit log规范方面是让我满意和欣赏的。另外本人在亲为commit log方面也是不能让自己满意的，这也是促使我思考commit log这块内容的一个初衷。

commit log承载着每次commit动作的context。一般来说context中至少要有一项内容，那就是此次代码变更的summary，这是最基本的要 求。如果你的commit log还是空着的，那你真该反思反思了，那是对自己和他人的不负责任。但无论是商业公司内部开发还是开源项目，commit context涉及到的因素往往不止一个，很多情况下commit context还与项目过程、质量保证流程以及项目使用的一些工具系统有 关联。我们来看两个知名开源项目的commit log样例吧。

[example1 - Linux Kernel]

audit: catch possible NULL audit buffers
It's possible for audit_log_start() to return NULL.  Handle it in the
various callers.

Signed-off-by: Kees Cook <keescook@chromium.org>
Cc: Al Viro <viro@zeniv.linux.org.uk>
Cc: Eric Paris <eparis@redhat.com>
Cc: Jeff Layton <jlayton@redhat.com>
Cc: "Eric W. Biederman" <ebiederm@xmission.com>
Cc: Julien Tinnes <jln@google.com>
Cc: Will Drewry <wad@google.com>
Cc: Steve Grubb <sgrubb@redhat.com>
Cc: Andrea Arcangeli <aarcange@redhat.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

这是Linux Kernel项目的一个commit log的内容。从这个log携带的context信息来看，我们能够清楚地了解如下一些内容：

- 修改的内核模块范围audit
- 修改的原因summary: to catch possible NULL audit buffers
- 这个patch从诞生到被merge到trunk过程中涉及到的相关的人员列表
- 这个patch由Who sign-off的。

将mail list放入到commit log中，这是Linux Kernel开发过程规范所要求的，同样也是质量保证的一个方法。在《如何加入Linux内核开发社区》系列文章中你可以了解到一些有关Linux Kernel开发过程的内容。从这个例子中我们主要可以看出commit context与Project过程、质量保证链条方面的相关性。

[example2 - Apache Subversion]

Fix issue #3498 – Subversion password stores freeze Eclipse

* subversion/libsvn_auth_gnome_keyring/gnome_keyring.c
  (simple_gnome_keyring_first_creds, simple_gnome_keyring_save_creds,
   ssl_client_cert_pw_gnome_keyring_first_creds,
   ssl_client_cert_pw_gnome_keyring_save_creds): If the keyring is locked
    and we are in interactive mode but have no unlock prompt function, don't
    throw a "GNOME Keyring is locked and we are non-interactive" error;
    instead, continue without unlocking it, so that the unlocking may be
    handled by the default GNOME Keyring unlock dialog box.

这是Apache Subversion项目的一个commit log的内容。同样从这个log携带的context信息来看，我们能够清楚地了解如下一些内容：

- 修改的代码范围subversion/libsvn_auth_gnome_keyring/gnome_keyring.c，包括括号中的函数名列表， 这个显然更为细致。
- 修改的原因summary: Fix issue #3498 – Subversion password stores freeze Eclipse
- 这个patch与问题跟踪系统的关联性 -issue #3498。

通过这个commit log，我们可以快速找到此patch对应的问题跟踪系统中的条目#3498，这样可以查看到一些更为细致的context信息。从这个例子我们主要能够 看出commit context与项目所使用的一些工具系统的关联。

综合以上可以看出良好的commit log是可以清楚全面反映commit context的。这里的“全面”是project-dependent的，是需要能够体现出涉及project的一切必要信息的：过程的、质量的、工具 的。

二、Commit log格式

Commit log没有放之四海而皆准的统一格式，而是project-dependent的。就我个人而言，我会在下面的几个问题上有纠结。

* 语言

不得不承认在创造编程语言方面，西方文化占了主导，语言中的关键字也多取自英语。虽然目前主流的语言以及新兴的语言都号称源码原生支持utf8或 unicode其他字符集格式，但却是很少见到在源文件中使用非英语命名变量或函数的，这也影响了我在commit log中对语言的选择 – 我基本上都是用英文编写commit log的。目前主流的版本控制工具都是支持unicode字符集的，你用中文提交也是没有任何问题的，尤其是在国内商业项目中，使用中文描述起来，理解上快且歧义少。我是不反对用中文写commit log的，但反感的是中英文混合写commit log（有些人用中文，有些人用英文）。每当批量看commit log时，中英文混在一起，一点美感都没有了。

commit log不是给最终用户看的，而是给开发维护人员看的。因此选择语言种类时要看这种语言是否能给开发维护人员的工作带来便利，精确全面地传达context。即便 应用是要发布给非洲人民，但若开发人员都是中国人，一样可以用中文编写commit log。

* 地道

说到“地道”，主要是针对你选择外语（大多数情况是英语）作为你commit log的承载语言时。就像生活在国外要用外国人熟悉的语言习惯与人交流似的，我们在用英语编写commit log时也要学会选用“地道”的词汇，远离Chinglish。当然想立即做到“地道”也不是那么容易，毕竟我们一直以来就按照Chinglish的思维去学 习英语的，一个比较好的方式就是多看看知名开源项目（比如linux kernel）的commit log，看看人家是如何选择词汇和组织句子的。其实Commit log中用到的词汇和句型很少，看多了也就找猫画虎的学会了。

* 规范

“没有规矩，不成方圆”，无论是商业软件项目，还是大型开源项目，莫不如此。如果要想很好的传达commit context，一个设计规范，内容全面的commit log格式是必不可少的。我们无需从头做起，很多开源项目在这方面都已经有一些良好的实践，比如上面提到的linux kernel的commit log convention，再比如这里有Apache Subversion的Commit log要求。TYPO3和FLOW3也有自己详细的Commit log说明。

制定规范时总体来说，注意以下几点：
– 格式简明扼要，只保留必要的项；
– 注意与项目过程、质量保证流程的结合，以及与第三方工具的关联（注意序号或ID的唯一性）；
– 对于规模较大的系统，可以考虑在log中体现影响的涉及的“子模块”或“子目录”名字或者逻辑功能的名字（比如前面linux kernel例子中的audit），这样便于快速定位本地commit的影响范畴。

三、Commit模板

如果像linux kernel或subversion那样涉及到过程、质量控制以及第三方工具的集成（比如问题跟踪系统、代码评审系统等）时，建议设置Commit log template(模板)以简化开发者commit log编写的工作。

* Subversion命令行客户端支持commit log模板

Subversion在命令行客户端侧暂无对模板的支持。不过可以通过一些trick模拟实现这个功能：

- 创建commit log模板log.tmpl，放在特定目录下，本例中放在用户的$HOME目录下
- 添加并导出环境变量SVN_EDITOR
         export SVN_EDITOR="rm svn-commit.tmp && cp ~/log.tmpl svn-commit.tmp && vi "

svn commit时，svn客户端会在当前路径下会执行类似$SVN_EDITOR svn-commit.tmp的命令，而svn-commit.tmp文件已经被替换为我们的模板文件，开发者只需按模板填写内容，并保存退出即可。如果 commit成功，svn客户端会删除当前目录下的svn-commit.tmp，否则svn-commit.tmp不会被删除，这将导致下次再提交 时，svn客户端检测到svn-commit.tmp的存在，从而新建立一个svn-commit.2.tmp的新文件，导致模板失效，这也是这个方法的 一个瑕疵。

* Git命令行支持commit log模板

Git是目前very hot的分布式版本管理工具，起步晚，但起点高，因此已经内置了对模板的支持，只需将模板文件配置一下即可。
         git config –global commit.template ~/log.tmpl

四、良好格式commit log的实施

即便有了良好格式的commit log的模板定义，但就我经验而言，实施起来也还会遇到诸多问题。commit行为是客户端发起的，要让所有开发者都能很好的使用模板并主动按模板提交需 要一些流程以及工具支持。比如在server段部署pre-commit hook，对提交的log格式进行检查，不符合模板格式的予以拒绝等。

对于与问题跟踪系统有关联的log格式，还要注意保持问题跟踪系统id或序号的唯一性，这显然是管理和过程方面的工作。

对于开源项目，一般merge到trunk需要owner的检查，所以反倒实施起来容易了些，只要有一篇内容丰富的 developer/community guide或convention之类的文档即可，多数知名的opensource project(比如linux kernel、subversion、apache httpd server、python等)都是有这类文档的，为这些project提交patch前是要好好阅读这些文档的，不能坏了规矩^_^。     
 

© 2013, bigwhite. 版权所有.