Git 笔记使用指南：非侵入式元数据管理、代码审查与团队协作

git%3Anotes by neolabhq/context-engineering-kit

282 周安装量

757 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/neolabhq/context-engineering-kit --skill git:notes

团队协作开发开发运维

🇨🇳中文介绍

Git 笔记

概述

Git 笔记允许你将元数据附加到提交（或任何 Git 对象）上，而无需修改对象本身。笔记是单独存储的，并会与提交信息一起显示。

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

核心概念

概念	描述
笔记引用	存储位置，默认为 `refs/notes/commits`
非侵入性	笔记永远不会修改原始对象的 SHA
命名空间	使用 `--ref` 来区分不同类别的笔记
显示	笔记会出现在 `git log` 和 `git show` 的输出中

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

任务	命令
添加笔记	`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>`

在变基时保留笔记

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

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

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

Git 笔记命令参考

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

# 为当前 HEAD 添加笔记
git notes add -m "Reviewed by Alice"

# 为特定提交添加笔记
git notes add -m "Tested on Linux" abc1234

# 从文件添加笔记
git notes add -F review-comments.txt abc1234

# 交互式添加笔记（打开编辑器）
git notes add abc1234

# 覆盖现有笔记
git notes add -f -m "Updated review status" abc1234

# 添加空笔记
git notes add --allow-empty abc1234

# 显示 HEAD 的笔记
git notes show

# 显示特定提交的笔记
git notes show abc1234

# 在日志中查看带有笔记的提交
git log --show-notes
git show abc1234

# 列出所有笔记
git notes list

# 列出特定对象的笔记
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>

# 追加到现有笔记（如果不存在则创建）
git notes append -m "Additional review comment" abc1234

# 从文件追加
git notes append -F more-comments.txt abc1234

# 追加多条消息
git notes append -m "Comment 1" -m "Comment 2" abc1234

# 交互式编辑笔记（打开编辑器）
git notes edit abc1234

# 编辑 HEAD 的笔记
git notes edit

# 移除 HEAD 的笔记
git notes remove

# 移除特定提交的笔记
git notes remove abc1234

# 移除多个提交的笔记
git notes remove abc1234 def5678 ghi9012

# 忽略缺失的笔记（如果笔记不存在则不报错）
git notes remove --ignore-missing abc1234

# 通过标准输入移除笔记（批量移除）
echo "abc1234" | git notes remove --stdin

# 将笔记从一个提交复制到另一个
git notes copy abc1234 def5678

# 将笔记复制到 HEAD
git notes copy abc1234

# 强制覆盖目标笔记
git notes copy -f abc1234 def5678

# 通过标准输入批量复制（在变基/拣选时有用）
echo "abc1234 def5678" | git notes copy --stdin

# 移除已不存在对象的笔记
git notes prune

# 模拟运行以查看将被清理的内容
git notes prune -n

# 详细输出
git notes prune -v

# 显示当前使用的笔记引用
git notes get-ref

使用多个命名空间

笔记可以组织到不同的命名空间（引用）中，用于不同的目的。

# 向特定命名空间添加笔记
git notes --ref=refs/notes/reviews add -m "Approved" abc1234

# 简写形式（假设前缀为 refs/notes/）
git notes --ref=reviews add -m "Approved" abc1234

# 查看特定命名空间的笔记
git notes --ref=reviews show abc1234

# 列出命名空间中的笔记
git notes --ref=reviews list

# 为会话设置默认笔记引用
export GIT_NOTES_REF=refs/notes/reviews
git notes add -m "Approved"

# 查看环境变量设置的引用中的笔记
git notes show abc1234

显示多个命名空间

# 在日志中显示特定的笔记命名空间
git log --notes=reviews

# 显示多个命名空间
git log --notes=reviews --notes=testing

# 显示所有笔记
git log --notes='*'

# 禁用笔记显示
git log --no-notes

当笔记存在于多个引用中或来自不同来源时，可以合并它们。

# 将笔记从另一个引用合并到当前引用
git notes merge 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 -v refs/notes/other

策略	行为
`manual`	交互式冲突解决（默认）
`ours`	冲突时保留本地笔记
`theirs`	冲突时保留远程笔记
`union`	连接两个笔记
`cat_sort_uniq`	连接、排序行、移除重复项

# 使用 manual 策略合并后发生冲突
# 在 .git/NOTES_MERGE_WORKTREE/ 中解决冲突

# 提交已解决的合并
git notes merge --commit

# 中止合并
git notes merge --abort

# 设置默认笔记引用
git config notes.displayRef refs/notes/reviews

# 显示多个笔记引用
git config --add notes.displayRef refs/notes/testing

# 设置笔记的合并策略
git config notes.mergeStrategy union

# 为特定命名空间设置合并策略
git config notes.reviews.mergeStrategy theirs

# 在变基期间保留笔记
git config notes.rewrite.rebase true

# 在修改提交时保留笔记
git config notes.rewrite.amend true

# 设置重写模式
git config notes.rewriteMode concatenate

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

[notes "reviews"]
    mergeStrategy = theirs

[notes.rewrite]
    rebase = true
    amend = true

# 标记提交为已审查
git notes --ref=reviews add -m "Reviewed-by: Alice <alice@example.com>" abc1234

# 添加审查评论
git notes --ref=reviews append -m "Consider extracting helper function" abc1234

# 查看审查状态
git log --notes=reviews --oneline

# 标记为已批准
git notes --ref=reviews add -f -m "APPROVED by Alice" abc1234

# 记录测试通过
git notes --ref=testing add -m "Tests passed: 2024-01-15
Platform: Linux x64
Coverage: 85%" abc1234

# 记录测试失败
git notes --ref=testing add -m "FAILED: Integration tests
See: https://ci.example.com/build/123" def5678

# 查看跨提交的测试状态
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 log --notes=audit --grep="Security review"

# 将笔记推送到远程仓库
git push origin refs/notes/reviews

# 从远程仓库获取笔记
git fetch origin refs/notes/reviews:refs/notes/reviews

# 推送所有笔记引用
git push origin 'refs/notes/*'

# 获取所有笔记引用
git fetch origin 'refs/notes/*:refs/notes/*'

# 为指定日期范围内某作者的所有提交添加笔记
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" HEAD~10..HEAD | xargs git notes remove --ignore-missing

🇺🇸English

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.

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

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>`

For complete command reference, see references/commands.md.

Essential Patterns

Code Review Tracking

# Mark reviewed
git notes --ref=reviews add -m "Reviewed-by: Alice <alice@example.com>" abc1234

# View review status
git log --notes=reviews --oneline

Sharing Notes

# Push to remote
git push origin refs/notes/reviews

# Fetch from remote
git fetch origin refs/notes/reviews:refs/notes/reviews

Preserving Through Rebase

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

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

Git Notes Command Reference

Complete reference for all git notes commands and options.

Basic Operations

Add a Note

# Add note to current 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

View Notes

# Show note for 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>

Append to Notes

# 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

Edit Notes

# Edit note interactively (opens editor)
git notes edit abc1234

# Edit note for HEAD
git notes edit

Remove Notes

# Remove note from 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

Copy Notes

# Copy note from one commit to another
git notes copy abc1234 def5678

# Copy note to 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

Prune Notes

# 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

Get Notes Reference

# Show current notes ref being used
git notes get-ref

Using Multiple Namespaces

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

Specify Notes Ref

# Add note to specific namespace
git notes --ref=refs/notes/reviews add -m "Approved" abc1234

# Shorthand (refs/notes/ prefix is assumed)
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

Environment Variable

# Set default notes ref for session
export GIT_NOTES_REF=refs/notes/reviews
git notes add -m "Approved"

# View notes from environment ref
git notes show abc1234

Display Multiple Namespaces

# 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

Merging Notes

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

Merge Notes Refs

# Merge notes from another ref into current
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

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

Resolve Merge Conflicts

# After merge conflict with manual strategy
# Resolve conflicts in .git/NOTES_MERGE_WORKTREE/

# Commit resolved merge
git notes merge --commit

# Abort merge
git notes merge --abort

Configuration Options

Git Config

# Set default notes ref
git config notes.displayRef refs/notes/reviews

# Display multiple notes refs
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

Sample .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

# 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

Test Results Annotation

# 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

Audit Trail

# 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"

Sharing Notes

# 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
git push origin 'refs/notes/*'

# Fetch all notes refs
git fetch origin 'refs/notes/*:refs/notes/*'

Bulk Operations

# 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

Weekly Installs

185

Repository

neolabhq/contex…ring-kit

GitHub Stars

699

First Seen

Feb 19, 2026

Installed on

opencode179

codex178

github-copilot178

gemini-cli177

kimi-cli175

cursor175

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

130,600 周安装

Git 笔记使用指南：非侵入式元数据管理、代码审查与团队协作

🇨🇳中文介绍

Git 笔记

概述

核心概念

相关 Skills

快速参考

常用模式

代码审查跟踪

共享笔记

在变基时保留笔记

常见错误

最佳实践

Git 笔记命令参考

基本操作

添加笔记

查看笔记

追加到笔记

编辑笔记

移除笔记

复制笔记

清理笔记

获取笔记引用

使用多个命名空间

指定笔记引用

环境变量

显示多个命名空间

合并笔记

合并笔记引用

合并策略

解决合并冲突

配置选项

Git 配置

示例 .gitconfig

工作流示例

代码审查跟踪

测试结果标注

审计跟踪

共享笔记

批量操作

🇺🇸English

Git Notes

Overview

Core Concepts

Quick Reference

Essential Patterns

Code Review Tracking

Sharing Notes

Preserving Through Rebase

Common Mistakes

Best Practices

Git Notes Command Reference

Basic Operations

Add a Note

View Notes

Append to Notes

Edit Notes

Remove Notes

Copy Notes

Prune Notes

Get Notes Reference

Using Multiple Namespaces

Specify Notes Ref

Environment Variable

Display Multiple Namespaces

Merging Notes

Merge Notes Refs

Merge Strategies

Resolve Merge Conflicts

Configuration Options

Git Config

Sample .gitconfig

Workflow Examples

Code Review Tracking

Test Results Annotation

Audit Trail

Sharing Notes

Bulk Operations

最新 Skills