Git Notes

Overview

概述

Git notes attach metadata to commits (or any Git object) without modifying the objects themselves. Notes are stored separately and displayed alongside commit messages.

Core principle: Add information to commits after creation without rewriting history.

Git notes可在不修改对象本身的情况下为提交（或任何Git对象）附加元数据。笔记存储在单独位置，并与提交消息一同显示。

核心原则： 在提交创建后添加信息，无需重写历史记录。

Core Concepts

核心概念

Concept	Description
Notes ref	Storage location, default `refs/notes/commits`
Non-invasive	Notes never modify SHA of original object
Namespaces	Use `--ref` for different note categories
Display	Notes appear in `git log` and `git show` output

概念	描述
Notes ref	存储位置，默认值为 `refs/notes/commits`
Non-invasive	笔记绝不会修改原始对象的SHA值
Namespaces	使用 `--ref` 参数区分不同笔记类别
Display	笔记会显示在 `git log` 和 `git show` 的输出中

Quick Reference

快速参考

Task	Command
Add note	`git notes add -m "message" <sha>`
View note	`git notes show <sha>`
Append	`git notes append -m "message" <sha>`
Edit	`git notes edit <sha>`
Remove	`git notes remove <sha>`
Use namespace	`git notes --ref=<name> <command>`
Push notes	`git push origin refs/notes/<name>`
Fetch notes	`git fetch origin refs/notes/<name>:refs/notes/<name>`
Show in log	`git log --notes=<name>`

For complete command reference, see

references/commands.md

.

任务	命令
添加笔记	`git notes add -m "message" <sha>`
查看笔记	`git notes show <sha>`
追加内容	`git notes append -m "message" <sha>`
编辑笔记	`git notes edit <sha>`
删除笔记	`git notes remove <sha>`
使用命名空间	`git notes --ref=<name> <command>`
推送笔记	`git push origin refs/notes/<name>`
获取笔记	`git fetch origin refs/notes/<name>:refs/notes/<name>`
在日志中显示	`git log --notes=<name>`

完整命令参考请查看

references/commands.md

。

Essential Patterns

核心使用模式

Code Review Tracking

代码评审跟踪

bash

undefined

bash

undefined

Mark reviewed

标记已评审

git notes --ref=reviews add -m "Reviewed-by: Alice alice@example.com" abc1234

View review status

查看评审状态

git log --notes=reviews --oneline

undefined

git log --notes=reviews --oneline

undefined

Sharing Notes

共享笔记

bash

undefined

bash

undefined

Push to remote

推送到远程仓库

git push origin refs/notes/reviews

Fetch from remote

从远程仓库获取

git fetch origin refs/notes/reviews:refs/notes/reviews

undefined

git fetch origin refs/notes/reviews:refs/notes/reviews

undefined

Preserving Through Rebase

在变基时保留笔记

bash

git config notes.rewrite.rebase true
git config notes.rewriteMode concatenate

bash

git config notes.rewrite.rebase true
git config notes.rewriteMode concatenate

Common Mistakes

常见错误

Mistake	Fix
Notes not showing in log	Specify ref: `git log --notes=reviews` or configure `notes.displayRef`
Notes lost after rebase	Enable: `git config notes.rewrite.rebase true`
Notes not on remote	Push explicitly: `git push origin refs/notes/commits`
"Note already exists" error	Use `-f` to overwrite or `append` to add

错误	修复方法
笔记未在日志中显示	指定ref： `git log --notes=reviews` 或配置 `notes.displayRef`
变基后笔记丢失	启用配置： `git config notes.rewrite.rebase true`
笔记未同步到远程仓库	显式推送： `git push origin refs/notes/commits`
"Note already exists" 错误	使用 `-f` 参数覆盖或 `append` 命令追加内容

Best Practices

最佳实践

Practice	Rationale
Use namespaces	Separate notes by purpose (reviews, testing, audit)
Be explicit about refs	Always specify `--ref` for non-default notes
Push notes explicitly	Document sharing procedures in team guidelines
Use append over add -f	Preserve note history when accumulating
Configure rewrite preservation	Run `git config notes.rewrite.rebase true` before rebasing

实践	理由
使用命名空间	按用途（评审、测试、审计）分离笔记
明确指定refs	对于非默认笔记，始终指定 `--ref` 参数
显式推送笔记	在团队指南中记录共享流程
使用append而非add -f	累积内容时保留笔记历史
配置重写保留	变基前执行 `git config notes.rewrite.rebase true`

Git Notes Command Reference

Git Notes 命令参考

Complete reference for all git notes commands and options.

所有git notes命令及选项的完整参考。

Basic Operations

基础操作

Add a Note

添加笔记

bash

undefined

bash

undefined

Add note to current HEAD

为当前HEAD添加笔记

git notes add -m "Reviewed by Alice"

Add note to specific commit

为指定提交添加笔记

git notes add -m "Tested on Linux" abc1234

Add note from file

从文件添加笔记

git notes add -F review-comments.txt abc1234

Add note interactively (opens editor)

交互式添加笔记（打开编辑器）

git notes add abc1234

Overwrite existing note

覆盖已有笔记

git notes add -f -m "Updated review status" abc1234

Add empty note

添加空笔记

git notes add --allow-empty abc1234

undefined

git notes add --allow-empty abc1234

undefined

View Notes

查看笔记

bash

undefined

bash

undefined

Show note for HEAD

查看HEAD的笔记

git notes show

Show note for specific commit

查看指定提交的笔记

git notes show abc1234

View commit with notes in log

在日志中查看包含笔记的提交

git log --show-notes git show abc1234

List all notes

列出所有笔记

git notes list

List note for specific object

列出指定对象的笔记

git notes list abc1234


**Example output with notes:**

commit abc1234def567890 Author: Developer dev@example.com Date: Mon Jan 15 10:00:00 2024 +0000

feat: implement user authentication

Notes: Reviewed by Alice Tested-by: CI Bot ci@example.com

undefined

git notes list abc1234


**包含笔记的示例输出：**

commit abc1234def567890 Author: Developer dev@example.com Date: Mon Jan 15 10:00:00 2024 +0000

feat: implement user authentication

Notes: Reviewed by Alice Tested-by: CI Bot ci@example.com

undefined

Append to Notes

追加笔记内容

bash

undefined

bash

undefined

Append to existing note (creates if doesn't exist)

追加到已有笔记（不存在则创建）

git notes append -m "Additional review comment" abc1234

Append from file

从文件追加内容

git notes append -F more-comments.txt abc1234

Append multiple messages

追加多条消息

git notes append -m "Comment 1" -m "Comment 2" abc1234

undefined

git notes append -m "Comment 1" -m "Comment 2" abc1234

undefined

Edit Notes

编辑笔记

bash

undefined

bash

undefined

Edit note interactively (opens editor)

交互式编辑笔记（打开编辑器）

git notes edit abc1234

Edit note for HEAD

编辑HEAD的笔记

git notes edit

undefined

git notes edit

undefined

Remove Notes

删除笔记

bash

undefined

bash

undefined

Remove note from HEAD

删除HEAD的笔记

git notes remove

Remove note from specific commit

删除指定提交的笔记

git notes remove abc1234

Remove notes from multiple commits

删除多个提交的笔记

git notes remove abc1234 def5678 ghi9012

Ignore missing notes (no error if note doesn't exist)

忽略不存在的笔记（笔记不存在时不报错）

git notes remove --ignore-missing abc1234

Remove notes via stdin (bulk removal)

通过标准输入批量删除

echo "abc1234" | git notes remove --stdin

undefined

echo "abc1234" | git notes remove --stdin

undefined

Copy Notes

复制笔记

bash

undefined

bash

undefined

Copy note from one commit to another

将笔记从一个提交复制到另一个提交

git notes copy abc1234 def5678

Copy note to HEAD

将笔记复制到HEAD

git notes copy abc1234

Force overwrite destination note

强制覆盖目标笔记

git notes copy -f abc1234 def5678

Bulk copy via stdin (useful with rebase/cherry-pick)

通过标准输入批量复制（适用于变基/拣选场景）

echo "abc1234 def5678" | git notes copy --stdin

undefined

echo "abc1234 def5678" | git notes copy --stdin

undefined

Prune Notes

清理无效笔记

bash

undefined

bash

undefined

Remove notes for objects that no longer exist

删除已不存在对象的笔记

git notes prune

Dry-run to see what would be pruned

预演清理操作（查看会被清理的内容）

git notes prune -n

Verbose output

显示详细输出

git notes prune -v

undefined

git notes prune -v

undefined

Get Notes Reference

获取笔记引用

bash

undefined

bash

undefined

Show current notes ref being used

显示当前使用的笔记ref

git notes get-ref

undefined

git notes get-ref

undefined

Using Multiple Namespaces

使用多命名空间

Notes can be organized into separate namespaces (refs) for different purposes.

笔记可按不同用途组织到单独的命名空间（refs）中。

Specify Notes Ref

指定笔记Ref

bash

undefined

bash

undefined

Add note to specific namespace

向指定命名空间添加笔记

git notes --ref=refs/notes/reviews add -m "Approved" abc1234

Shorthand (refs/notes/ prefix is assumed)

简写形式（默认添加refs/notes/前缀）

git notes --ref=reviews add -m "Approved" abc1234

View notes from specific namespace

查看指定命名空间的笔记

git notes --ref=reviews show abc1234

List notes in namespace

列出命名空间中的笔记

git notes --ref=reviews list

undefined

git notes --ref=reviews list

undefined

Environment Variable

环境变量设置

bash

undefined

bash

undefined

Set default notes ref for session

设置会话默认笔记ref

export GIT_NOTES_REF=refs/notes/reviews git notes add -m "Approved"

View notes from environment ref

查看环境变量指定ref的笔记

git notes show abc1234

undefined

git notes show abc1234

undefined

Display Multiple Namespaces

显示多命名空间

bash

undefined

bash

undefined

Show specific notes namespace in log

在日志中显示指定命名空间的笔记

git log --notes=reviews

Show multiple namespaces

显示多个命名空间的笔记

git log --notes=reviews --notes=testing

Show all notes

显示所有笔记

git log --notes='*'

Disable notes display

禁用笔记显示

git log --no-notes

undefined

git log --no-notes

undefined

Merging Notes

合并笔记

When notes exist in multiple refs or from different sources, they can be merged.

当多个ref或不同来源存在笔记时，可进行合并。

Merge Notes Refs

合并笔记Ref

bash

undefined

bash

undefined

Merge notes from another ref into current

将其他ref的笔记合并到当前ref

git notes merge refs/notes/other

Merge with strategy

使用指定策略合并

git notes merge -s union refs/notes/other git notes merge -s ours refs/notes/other git notes merge -s theirs refs/notes/other git notes merge -s cat_sort_uniq refs/notes/other

Quiet merge

静默合并

git notes merge -q refs/notes/other

Verbose merge

详细输出合并过程

git notes merge -v refs/notes/other

undefined

git notes merge -v refs/notes/other

undefined

Merge Strategies

合并策略

Strategy	Behavior
`manual`	Interactive conflict resolution (default)
`ours`	Keep local note on conflict
`theirs`	Keep remote note on conflict
`union`	Concatenate both notes
`cat_sort_uniq`	Concatenate, sort lines, remove duplicates

策略	行为
`manual`	交互式解决冲突（默认）
`ours`	冲突时保留本地笔记
`theirs`	冲突时保留远程笔记
`union`	拼接双方笔记
`cat_sort_uniq`	拼接、排序行并移除重复内容

Resolve Merge Conflicts

解决合并冲突

bash

undefined

bash

undefined

After merge conflict with manual strategy

使用manual策略出现合并冲突后

Resolve conflicts in .git/NOTES_MERGE_WORKTREE/

在.git/NOTES_MERGE_WORKTREE/中解决冲突

Commit resolved merge

提交已解决的合并

git notes merge --commit

Abort merge

中止合并

git notes merge --abort

undefined

git notes merge --abort

undefined

Configuration Options

配置选项

Git Config

Git配置

bash

undefined

bash

undefined

Set default notes ref

设置默认显示的笔记ref

git config notes.displayRef refs/notes/reviews

Display multiple notes refs

添加多个显示的笔记ref

git config --add notes.displayRef refs/notes/testing

Set merge strategy for notes

设置笔记合并策略

git config notes.mergeStrategy union

Set merge strategy for specific namespace

为指定命名空间设置合并策略

git config notes.reviews.mergeStrategy theirs

Preserve notes during rebase

变基时保留笔记

git config notes.rewrite.rebase true

Preserve notes during amend

修改提交时保留笔记

git config notes.rewrite.amend true

Set rewrite mode

设置重写模式

git config notes.rewriteMode concatenate

undefined

git config notes.rewriteMode concatenate

undefined

Sample .gitconfig

示例.gitconfig

gitconfig

[notes]
    displayRef = refs/notes/reviews
    displayRef = refs/notes/testing
    mergeStrategy = union

[notes "reviews"]
    mergeStrategy = theirs

[notes.rewrite]
    rebase = true
    amend = true

gitconfig

[notes]
    displayRef = refs/notes/reviews
    displayRef = refs/notes/testing
    mergeStrategy = union

[notes "reviews"]
    mergeStrategy = theirs

[notes.rewrite]
    rebase = true
    amend = true

Workflow Examples

工作流示例

Code Review Tracking

代码评审跟踪

bash

undefined

bash

undefined

Mark commit as reviewed

标记提交为已评审

git notes --ref=reviews add -m "Reviewed-by: Alice alice@example.com" abc1234

Add review comments

添加评审意见

git notes --ref=reviews append -m "Consider extracting helper function" abc1234

View review status

查看评审状态

git log --notes=reviews --oneline

Mark as approved

标记为已批准

git notes --ref=reviews add -f -m "APPROVED by Alice" abc1234

undefined

git notes --ref=reviews add -f -m "APPROVED by Alice" abc1234

undefined

Test Results Annotation

测试结果标注

bash

undefined

bash

undefined

Record test pass

记录测试通过

git notes --ref=testing add -m "Tests passed: 2024-01-15 Platform: Linux x64 Coverage: 85%" abc1234

Record test failure

记录测试失败

git notes --ref=testing add -m "FAILED: Integration tests See: https://ci.example.com/build/123" def5678

View test status across commits

查看所有提交的测试状态

git log --notes=testing --oneline

undefined

git log --notes=testing --oneline

undefined

Audit Trail

审计追踪

bash

undefined

bash

undefined

Add audit note

添加审计笔记

git notes --ref=audit add -m "Security review: PASSED Reviewer: Security Team Date: 2024-01-15 Ticket: SEC-456" abc1234

Query audit status

查询审计状态

git log --notes=audit --grep="Security review"

undefined

git log --notes=audit --grep="Security review"

undefined

Sharing Notes

共享笔记

bash

undefined

bash

undefined

Push notes to remote

将笔记推送到远程仓库

git push origin refs/notes/reviews

Fetch notes from remote

从远程仓库获取笔记

git fetch origin refs/notes/reviews:refs/notes/reviews

Push all notes refs

推送所有笔记refs

git push origin 'refs/notes/*'

Fetch all notes refs

获取所有笔记refs

git fetch origin 'refs/notes/:refs/notes/'

undefined

git fetch origin 'refs/notes/:refs/notes/'

undefined

Bulk Operations

批量操作

bash

undefined

bash

undefined

Add notes to all commits by author in date range

为指定作者在指定日期范围内的所有提交添加笔记

git log --format="%H" --author="Alice" --since="2024-01-01" |
while read sha; do git notes add -m "Author verified" "$sha" done

Remove notes from range of commits

删除指定范围内提交的笔记

git log --format="%H" HEAD~10..HEAD | xargs git notes remove --ignore-missing

undefined

git log --format="%H" HEAD~10..HEAD | xargs git notes remove --ignore-missing

undefined

git-notes

Original

Translation

Git Notes

Git Notes

Overview

概述

Core Concepts

核心概念

Quick Reference

快速参考

Essential Patterns

核心使用模式

Code Review Tracking

代码评审跟踪

Mark reviewed

标记已评审

View review status

查看评审状态

Sharing Notes

共享笔记

Push to remote

推送到远程仓库

Fetch from remote

从远程仓库获取

Preserving Through Rebase

在变基时保留笔记

Common Mistakes

常见错误

Best Practices

最佳实践

Git Notes Command Reference

Git Notes 命令参考

Basic Operations

基础操作

Add a Note

添加笔记

Add note to current HEAD

为当前HEAD添加笔记

Add note to specific commit

为指定提交添加笔记

Add note from file

从文件添加笔记

Add note interactively (opens editor)

交互式添加笔记（打开编辑器）

Overwrite existing note

覆盖已有笔记

Add empty note

添加空笔记

View Notes

查看笔记

Show note for HEAD

查看HEAD的笔记

Show note for specific commit

查看指定提交的笔记

View commit with notes in log

在日志中查看包含笔记的提交

List all notes

列出所有笔记

List note for specific object

列出指定对象的笔记

Append to Notes

追加笔记内容

Append to existing note (creates if doesn't exist)

追加到已有笔记（不存在则创建）

Append from file

从文件追加内容

Append multiple messages

追加多条消息

Edit Notes

编辑笔记

Edit note interactively (opens editor)

交互式编辑笔记（打开编辑器）

Edit note for HEAD

编辑HEAD的笔记

Remove Notes

删除笔记

Remove note from HEAD

删除HEAD的笔记

Remove note from specific commit