git notes 是什么
git notes 在不修改提交内容的前提下给提交挂注解：评审结论、CI 结果、迁移标记都可以写；注解存放在独立引用空间（默认 refs/notes/commits），不改提交哈希，也默认不随 push 同步——不显式推送，别人查看时就是一片空白。它适合承载「附加信息」，不适合替代提交信息。
基本信息
| 常用命令 | git notes add/show/append/remove/list |
|---|---|
| 引用空间 | refs/notes/commits（--ref 可自定义） |
| 同步 | git push origin refs/notes/commits 显式推送 |
| 查看 | git log --show-notes=commits 显示注解 |
| 特点 | 不改提交、不进提交哈希 |
| 注意 | 默认不随常规 push 走 |
典型使用场景
- 评审留痕：给已合入的提交补评审结论，不动提交信息
- 自动化写入：CI 把测试与扫描结果挂到对应提交，评审时随日志一起可见
- 迁移标记：历史整理时标注改写前后的对应关系
- 审计补充：补记背景说明，提交信息保持稳定
- 团队协作：先约定推送与读取习惯（含 refspec 与合并策略），再用于共享
- 排查辅助：给可疑提交挂调查标记
常用示例
常用示例
git notes add -m '已通过安全评审' <sha> # 给指定提交加注解
git notes show <sha> # 查看单个提交的注解
git notes append -m '回归通过' <sha> # 追加内容，不覆盖已有注解
git log --show-notes=commits -3 # 日志里显示注解
git push origin refs/notes/commits # 显式推送注解引用命令与用途
| 命令 | 用途 | 备注 |
|---|---|---|
| add | 新增注解 | 已存在时需 -f 覆盖，慎用 |
| show | 查看注解 | 无注解时报错 |
| append | 追加一行 | 适合自动化逐条补充 |
| list | 列出有注解的对象 | 快速盘点 |
| push refs/notes/commits | 同步注解 | 默认不随 push 走 |
适合自动化写入构建与扫描结果；对外协作前确认接收方会读取 notes（并已拉取该引用），否则信息形同隐藏。
多人同时更新同一条注解不会自动合并：用 git notes merge 处理或提前约定负责人，最省事。
仓库搬迁时别只带走分支与标签：notes 是独立引用空间，漏了会丢注解；备份与镜像同步要显式包含 refs/notes/*。