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对象)附加元数据。笔记存储在单独位置,并与提交消息一同显示。
核心原则: 在提交创建后添加信息,无需重写历史记录。
| Concept | Description |
|---|
| Notes ref | Storage location, default |
| Non-invasive | Notes never modify SHA of original object |
| Namespaces | Use for different note categories |
| Display | Notes appear in and output |
| 概念 | 描述 |
|---|
| Notes ref | 存储位置,默认值为 |
| Non-invasive | 笔记绝不会修改原始对象的SHA值 |
| Namespaces | 使用 参数区分不同笔记类别 |
| Display | 笔记会显示在 和 的输出中 |
| Task | Command |
|---|
| Add note | git notes add -m "message" <sha>
|
| View note | |
| Append | git notes append -m "message" <sha>
|
| Edit | |
| Remove | |
| 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 | |
For complete command reference, see
.
| 任务 | 命令 |
|---|
| 添加笔记 | git notes add -m "message" <sha>
|
| 查看笔记 | |
| 追加内容 | git notes append -m "message" <sha>
|
| 编辑笔记 | |
| 删除笔记 | |
| 使用命名空间 | git notes --ref=<name> <command>
|
| 推送笔记 | git push origin refs/notes/<name>
|
| 获取笔记 | git fetch origin refs/notes/<name>:refs/notes/<name>
|
| 在日志中显示 | |
Code Review Tracking
代码评审跟踪
git notes --ref=reviews add -m "Reviewed-by: Alice alice@example.com" abc1234
git notes --ref=reviews add -m "Reviewed-by: Alice alice@example.com" abc1234
git log --notes=reviews --oneline
git log --notes=reviews --oneline
git push origin refs/notes/reviews
git push origin refs/notes/reviews
git fetch origin refs/notes/reviews:refs/notes/reviews
git fetch origin refs/notes/reviews:refs/notes/reviews
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
| Mistake | Fix |
|---|
| Notes not showing in log | Specify ref: or configure |
| 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 to overwrite or to add |
| 错误 | 修复方法 |
|---|
| 笔记未在日志中显示 | 指定ref: 或配置 |
| 变基后笔记丢失 | 启用配置:git config notes.rewrite.rebase true
|
| 笔记未同步到远程仓库 | 显式推送:git push origin refs/notes/commits
|
| "Note already exists" 错误 | 使用 参数覆盖或 命令追加内容 |
| Practice | Rationale |
|---|
| Use namespaces | Separate notes by purpose (reviews, testing, audit) |
| Be explicit about refs | Always specify 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 | 对于非默认笔记,始终指定 参数 |
| 显式推送笔记 | 在团队指南中记录共享流程 |
| 使用append而非add -f | 累积内容时保留笔记历史 |
| 配置重写保留 | 变基前执行 git config notes.rewrite.rebase true
|
Git Notes Command Reference
Git Notes 命令参考
Complete reference for all git notes commands and options.
Add note to current HEAD
为当前HEAD添加笔记
git notes add -m "Reviewed by Alice"
git notes add -m "Reviewed by Alice"
Add note to specific commit
为指定提交添加笔记
git notes add -m "Tested on Linux" abc1234
git notes add -m "Tested on Linux" abc1234
Add note from file
从文件添加笔记
git notes add -F review-comments.txt abc1234
git notes add -F review-comments.txt abc1234
Add note interactively (opens editor)
交互式添加笔记(打开编辑器)
Overwrite existing note
覆盖已有笔记
git notes add -f -m "Updated review status" abc1234
git notes add -f -m "Updated review status" abc1234
git notes add --allow-empty abc1234
git notes add --allow-empty abc1234
Show note for HEAD
查看HEAD的笔记
Show note for specific commit
查看指定提交的笔记
View commit with notes in log
在日志中查看包含笔记的提交
git log --show-notes
git show abc1234
git log --show-notes
git show abc1234
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
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
Append to existing note (creates if doesn't exist)
追加到已有笔记(不存在则创建)
git notes append -m "Additional review comment" abc1234
git notes append -m "Additional review comment" abc1234
git notes append -F more-comments.txt abc1234
git notes append -F more-comments.txt abc1234
Append multiple messages
追加多条消息
git notes append -m "Comment 1" -m "Comment 2" abc1234
git notes append -m "Comment 1" -m "Comment 2" abc1234
Edit note interactively (opens editor)
交互式编辑笔记(打开编辑器)
Edit note for HEAD
编辑HEAD的笔记
Remove note from HEAD
删除HEAD的笔记
Remove note from specific commit
删除指定提交的笔记
Remove notes from multiple commits
删除多个提交的笔记
git notes remove abc1234 def5678 ghi9012
git notes remove abc1234 def5678 ghi9012
Ignore missing notes (no error if note doesn't exist)
忽略不存在的笔记(笔记不存在时不报错)
git notes remove --ignore-missing abc1234
git notes remove --ignore-missing abc1234
Remove notes via stdin (bulk removal)
通过标准输入批量删除
echo "abc1234" | git notes remove --stdin
echo "abc1234" | git notes remove --stdin
Copy note from one commit to another
将笔记从一个提交复制到另一个提交
git notes copy abc1234 def5678
git notes copy abc1234 def5678
Copy note to HEAD
将笔记复制到HEAD
Force overwrite destination note
强制覆盖目标笔记
git notes copy -f abc1234 def5678
git notes copy -f abc1234 def5678
Bulk copy via stdin (useful with rebase/cherry-pick)
通过标准输入批量复制(适用于变基/拣选场景)
echo "abc1234 def5678" | git notes copy --stdin
echo "abc1234 def5678" | git notes copy --stdin
Remove notes for objects that no longer exist
删除已不存在对象的笔记
Dry-run to see what would be pruned
预演清理操作(查看会被清理的内容)
Get Notes Reference
获取笔记引用
Show current notes ref being used
显示当前使用的笔记ref
Using Multiple Namespaces
使用多命名空间
Notes can be organized into separate namespaces (refs) for different purposes.
笔记可按不同用途组织到单独的命名空间(refs)中。
Add note to specific namespace
向指定命名空间添加笔记
git notes --ref=refs/notes/reviews add -m "Approved" abc1234
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
git notes --ref=reviews add -m "Approved" abc1234
View notes from specific namespace
查看指定命名空间的笔记
git notes --ref=reviews show abc1234
git notes --ref=reviews show abc1234
List notes in namespace
列出命名空间中的笔记
git notes --ref=reviews list
git notes --ref=reviews list
Environment Variable
环境变量设置
Set default notes ref for session
设置会话默认笔记ref
export GIT_NOTES_REF=refs/notes/reviews
git notes add -m "Approved"
export GIT_NOTES_REF=refs/notes/reviews
git notes add -m "Approved"
View notes from environment ref
查看环境变量指定ref的笔记
Display Multiple Namespaces
显示多命名空间
Show specific notes namespace in log
在日志中显示指定命名空间的笔记
Show multiple namespaces
显示多个命名空间的笔记
git log --notes=reviews --notes=testing
git log --notes=reviews --notes=testing
Disable notes display
禁用笔记显示
When notes exist in multiple refs or from different sources, they can be merged.
Merge notes from another ref into current
将其他ref的笔记合并到当前ref
git notes merge refs/notes/other
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
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
git notes merge -q refs/notes/other
git notes merge -q refs/notes/other
git notes merge -v refs/notes/other
git notes merge -v refs/notes/other
| Strategy | Behavior |
|---|
| Interactive conflict resolution (default) |
| Keep local note on conflict |
| Keep remote note on conflict |
| Concatenate both notes |
| Concatenate, sort lines, remove duplicates |
| 策略 | 行为 |
|---|
| 交互式解决冲突(默认) |
| 冲突时保留本地笔记 |
| 冲突时保留远程笔记 |
| 拼接双方笔记 |
| 拼接、排序行并移除重复内容 |
Resolve Merge Conflicts
解决合并冲突
After merge conflict with manual strategy
使用manual策略出现合并冲突后
Resolve conflicts in .git/NOTES_MERGE_WORKTREE/
在.git/NOTES_MERGE_WORKTREE/中解决冲突
Commit resolved merge
提交已解决的合并
Configuration Options
配置选项
Set default notes ref
设置默认显示的笔记ref
git config notes.displayRef refs/notes/reviews
git config notes.displayRef refs/notes/reviews
Display multiple notes refs
添加多个显示的笔记ref
git config --add notes.displayRef refs/notes/testing
git config --add notes.displayRef refs/notes/testing
Set merge strategy for notes
设置笔记合并策略
git config notes.mergeStrategy union
git config notes.mergeStrategy union
Set merge strategy for specific namespace
为指定命名空间设置合并策略
git config notes.reviews.mergeStrategy theirs
git config notes.reviews.mergeStrategy theirs
Preserve notes during rebase
变基时保留笔记
git config notes.rewrite.rebase true
git config notes.rewrite.rebase true
Preserve notes during amend
修改提交时保留笔记
git config notes.rewrite.amend true
git config notes.rewrite.amend true
git config notes.rewriteMode concatenate
git config notes.rewriteMode concatenate
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
Code Review Tracking
代码评审跟踪
Mark commit as reviewed
标记提交为已评审
git notes --ref=reviews add -m "Reviewed-by: Alice alice@example.com" abc1234
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
git notes --ref=reviews append -m "Consider extracting helper function" abc1234
git log --notes=reviews --oneline
git log --notes=reviews --oneline
git notes --ref=reviews add -f -m "APPROVED by Alice" abc1234
git notes --ref=reviews add -f -m "APPROVED by Alice" abc1234
Test Results Annotation
测试结果标注
git notes --ref=testing add -m "Tests passed: 2024-01-15
Platform: Linux x64
Coverage: 85%" abc1234
git notes --ref=testing add -m "Tests passed: 2024-01-15
Platform: Linux x64
Coverage: 85%" abc1234
Record test failure
记录测试失败
View test status across commits
查看所有提交的测试状态
git log --notes=testing --oneline
git log --notes=testing --oneline
git notes --ref=audit add -m "Security review: PASSED
Reviewer: Security Team
Date: 2024-01-15
Ticket: SEC-456" abc1234
git notes --ref=audit add -m "Security review: PASSED
Reviewer: Security Team
Date: 2024-01-15
Ticket: SEC-456" abc1234
git log --notes=audit --grep="Security review"
git log --notes=audit --grep="Security review"
Push notes to remote
将笔记推送到远程仓库
git push origin refs/notes/reviews
git push origin refs/notes/reviews
Fetch notes from remote
从远程仓库获取笔记
git fetch origin refs/notes/reviews:refs/notes/reviews
git fetch origin refs/notes/reviews:refs/notes/reviews
Push all notes refs
推送所有笔记refs
git push origin 'refs/notes/*'
git push origin 'refs/notes/*'
Fetch all notes refs
获取所有笔记refs
git fetch origin 'refs/notes/:refs/notes/'
git fetch origin 'refs/notes/:refs/notes/'
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
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
git log --format="%H" HEAD~10..HEAD | xargs git notes remove --ignore-missing