阅读历史

提交备注

提交消息写完一次就冻结了:改它就等于重写这个提交,给它一个新的哈希,并且让所有已经拿到旧提交的人都乱套。提交后一个小时这么做没问题,一周之后就不可能了。

git notes 就是那条出路。一条备注存放在提交旁边,位于 refs/notes/commits 之下,附加一条备注不会让提交有一个字节的变化。所以它对已经发布出去的历史照样有效——而那恰恰是你最想补点什么的时候。

典型用法:批准它的那次审阅、它关闭的工单、它当初为什么被还原、它随哪个发布版本上线。

写一条

选中一个提交。消息下方有一个备注区域:添加备注,输入内容,保存备注。多行也没问题。

在一个已推送提交的消息下方写一条备注,然后保存

保存备注是一次普通的 Gitcito 操作——它会弹出提示,而撤销会把之前的文字放回去,包括恢复一条你删掉的备注。

清空文字再保存就会删除这条备注;世上没有「空备注」这种东西。

找到一条

在普通的日志里备注是看不见的,这正是大多数人从来没发现过它们的主要原因。Gitcito 会在图的消息列里,给带有备注的提交打上一个小小的备注图标,于是这条标注不必事先知道它存在也能被找到。

在命令行里,git log --notes 会把它们打印在每条消息下面。

分享它们

这一点会让所有人吃惊:普通的 git push 不会推送备注,普通的 git fetch 也不会获取它们。 它们活在 refs/heads 和 refs/tags 之外,所以默认的 refspec 会完全跳过它们。写在你笔记本上的备注就一直待在你的笔记本上,直到有人明确地把它们搬走。

工具 → 备注 → 推送备注 / 获取备注,按远程逐个进行。它们执行的是:

git push <remote> refs/notes/commits
git fetch <remote> +refs/notes/commits:refs/notes/commits

会移动的只有提交备注这一个 ref——Gitcito 自己的机器本地 ref(比如本地 CI的判定)是有意不发布的。

有些托管方还需要在自己那一侧启用或允许备注;被拒绝是托管方的策略,不是 Gitcito 的限制。

没有共享的远程,或者没有写权限?安全分享可以把一个仓库的备注打进一个加密文件,队友直接导入即可——导入前能预览将要落下的内容,对分叉的备注有明确的覆盖选择。

局限

  • 只有一个 notes ref。 Gitcito 读写的是默认的 refs/notes/commits。自定义命名空间(git notes --ref=review)没有暴露出来——用了它们的仓库在这里看不到那些备注。
  • 不会合并分叉的备注。 如果两个人给同一个提交都写了标注并都推送,git 会拒绝第二次推送。要解决它,得在终端里用 git notes merge。
  • 备注不会被清除操作的备份收录,也不会被快照收录。它们是普通的 ref,在常规操作中能存活下来,但一个从头重新克隆的仓库一开始是没有它们的。

另请参阅:提交 · 提交图

在 GitHub 上改进这份翻译