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