Git notes：Git 最酷、最不受欢迎的功能

简而言之，Git notes 对于从自动化系统（如工单或构建系统）追加注释非常有用，但对于与其他开发者进行交互式对话则不太适合（至少目前还不太适合）。

– Scott Chacon，GitHub.blog，2010 年 8 月

Git notes几乎是一个秘密，很多开发人员都不知道它们的存在。

由于git notes使用方法不直观且复杂，导致它们很难被普通用户理解和使用。

但是工程师们不断重新发现Git notes，试图将元数据(与代码或项目相关的附加信息)存储在Git中

Git notes是一个强大的工具。如果它们更为人所知且更易于使用，它们可以解决很多问题。

🧐 什么是 git notes？

git notes 的一个常见用途是将其元数据附加到 git提交上。

一旦一个git提交成为了历史。在存储库的深处修改提交消息是不可能的。

但是git notes允许您在一个特殊的名称空间中修改旧提交的新信息。而且他们有能力做得更多。

Git笔记存储关于Git跟踪的任何对象的元数据，包括提交（commits）、文件快照（blobs）和目录树（trees）。所有这些都可以在不修改对象本身的情况下进行。

要给存储库的最新提交添加笔记，您可以按照以下方式进行操作：

git notes add -m 'Acked-by: <tyler@tylercipriani.com>'

然后在git log中显示如下：

commit 1ef8b30ab7fc218ccc85c9a6411b1d2dd2925a16
Author: Tyler Cipriani <thcipriani@gmail.com> 
Date: Thu Nov 17 16:51:43 2022 -0700 
    Initial commit 
    Notes: 
        Acked-by: <tyler@tylercipriani.com>

🥾 Git notes的使用

Git 项目本身提供了一个在实际环境中使用 Git notes的例子。它们将每个提交与其在邮件列表上的讨论相关联。

例如：

commit 00f09d0e4b1826ee0519ea64e919515032966450 
Author: <redacted> 
Date: Thu Jan 28 02:05:55 2010 +0100
    bash: support 'git notes' and its subcommands
    ...
Notes (amlog): 
    Message-Id: <1264640755-22447-1-git-send-email-szeder@ira.uka.de>

开发人员在提交中添加了一条注释，以便引导那些愿意尝试新补丁或新功能的用户找到讨论此补丁的主题帖，以便更好地了解补丁的内容和可能的问题。

其他人在使用注释进行类似以下的事情：

跟踪每个提交或分支花费的时间
将审查和测试信息添加到 git 日志
完全分布式代码审查

📦 将代码审查和测试结果存储在 git 笔记中

这是一个对所有版本管理系统的呼吁：请将代码审查的元数据离线化，嵌入到Git中。

Gerrit's reviewnotes插件是一个很好的例子，它可以很方便地在Git日志中查看代码审查人员的信息。

git fetch origin refs/notes/review:refs/notes/review 
git log --show-notes=review

上面的命令会显示所有标准的git log信息，以及关于运行的测试和代码审核人员的信息。这一切都可以在不必打开浏览器的情况下完成。

commit d1d17908d2a97f057887a4afbd99f6c40be56849 
Author: User <user@example.com> 
Date: Sun Mar 27 18:10:51 2022 +0200 
    Change the thing 
Notes (review): 
    Verified+1: SonarQube Bot 
    Verified+2: jenkins-bot 
    Code-Review+2: Reviewer Human <reviewerhuman@wikimedia.org> 
    Submitted-by: jenkins-bot 
    Submitted-at: Tue, 14 Jun 2022 21:59:58 +0000 
    Reviewed-on: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/774005 
    Project: mediawiki/core 
    Branch: refs/heads/master

💠 git notes 中的分布式代码审查

有动机的黑客可以操纵和扩展git notes，将它们用作分布式存储来存储任何疯狂的想法。

有人在Google组织中组装了一个完整的代码审查系统，基于git notes，并称其为git-appraise

该工具的作者将其称为“完全分布式的代码审查”系统，与GitHub、GitLab或任何其他代码托管平台无关。该系统支持您：

请求对变更进行审查。
对更改发表评论
审查并合并更改

即使 GitHub 出现故障，您也可以在本地计算机上执行所有这些操作。另外，它还配备了一个不美观的网络界面，如果您喜欢的话。

😭 没有人用 git notes

使用Git notes可能会有些麻烦。

GitHub在2014年选择停止显示提交注释，但并未给出详细的解释。

对于提交（commits），你可以通过在gitconfig中配置一些高级选项，使查看和添加注释变得更加方便。但是对于存储关于对象（blobs）或树（trees）的注释来说，就不太容易了。你需要对Git的内部实现有一定的了解才能进行操作。

目前来说，Git notes在某种程度上确实被边缘化了。它们受限于晦涩而笨拙的界面和有限的采用率，很容易被忽视和遗忘

🗽 独立于代码托管平台

Git是一个分布式的代码审查系统。但是，许多Git仓库的价值最终被锁定在像GitHub这样的代码托管平台中。

Git notes 可以被视为迈向一种替代方法的路径。

Git分发了一段代码的历史。而Git notes可以使得分发整个项目的历史成为可能。

使用git notes 以避免强制推送可能带来的问题和不确定性。
一些较大的项目使用了基于 Git Notes 实现的代码审查系统。
通过自动获取注释并在git log中显示它们：

$ git config --add \
remote.origin.fetch \ 
'+refs/notes/*:refs/notes/*' 
$ git config \
notes.displayRef \ 
'refs/notes/*'

【译】Git 笔记：Git 最酷、最不受欢迎的功能