Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc - provides git notes commands and patterns for attaching non-invasive metadata to Git objects.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc - provides git notes commands and patterns for attaching non-invasive metadata to Git objects.
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.
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>
# 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 sessionexport 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
# 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" | \
whileread 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
