Git Notes

NeoLabHQ/context-engineering-kit/antigravity/skills/git-notes

by NeoLabHQ23e2428e809d77717f8acc9659c374a3a1fcb93eNo licenseListed Oct 9, 2026Updated Oct 9, 2026

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.

Instructions onlySoftware Development

AI-generated overview

Reference for using git notes to attach metadata to commits without rewriting history.

What it does: Provides git notes commands and patterns for attaching non-invasive metadata to Git commits and other objects. It covers adding, viewing, appending, editing, removing, copying and pruning notes, plus namespaces, merging, configuration and sharing via push and fetch. It produces command guidance and workflow examples rather than files or scripts.
When to use it: Use when you need to annotate commits after creation without changing their SHAs, such as tracking review status, test results, code quality notes or audit trails. Also useful for supplementing commit messages post-hoc or organizing notes into separate namespaces.
Requirements: Requires a Git installation and a repository to operate on; remote sharing needs network access and push/fetch permissions. Ships no scripts; it is instructions only.

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

bash

# Mark reviewedgit notes --ref=reviews add -m "Reviewed-by: Alice <[email protected]>" abc1234
# View review statusgit log --notes=reviews --oneline

# Mark reviewedgit notes --ref=reviews add -m "Reviewed-by: Alice <[email protected]>" abc1234
# View review statusgit log --notes=reviews --oneline

Sharing Notes

bash

# Push to remotegit push origin refs/notes/reviews
# Fetch from remotegit fetch origin refs/notes/reviews:refs/notes/reviews

# Push to remotegit push origin refs/notes/reviews
# Fetch from remotegit fetch origin refs/notes/reviews:refs/notes/reviews

Preserving Through Rebase

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

bash

# Add note to current HEADgit notes add -m "Reviewed by Alice"
# Add note to specific commitgit notes add -m "Tested on Linux" abc1234
# Add note from filegit notes add -F review-comments.txt abc1234
# Add note interactively (opens editor)git notes add abc1234
# Overwrite existing notegit notes add -f -m "Updated review status" abc1234
# Add empty notegit notes add --allow-empty abc1234

# Add note to current HEADgit notes add -m "Reviewed by Alice"
# Add note to specific commitgit notes add -m "Tested on Linux" abc1234
# Add note from filegit notes add -F review-comments.txt abc1234
# Add note interactively (opens editor)git notes add abc1234
# Overwrite existing notegit notes add -f -m "Updated review status" abc1234
# Add empty notegit notes add --allow-empty abc1234

View Notes

bash

# Show note for HEADgit notes show
# Show note for specific commitgit notes show abc1234
# View commit with notes in loggit log --show-notesgit show abc1234
# List all notesgit notes list
# List note for specific objectgit notes list abc1234

# Show note for HEADgit notes show
# Show note for specific commitgit notes show abc1234
# View commit with notes in loggit log --show-notesgit show abc1234
# List all notesgit notes list
# List note for specific objectgit notes list abc1234

Example output with notes:

commit abc1234def567890Author: Developer <[email protected]>Date:   Mon Jan 15 10:00:00 2024 +0000
    feat: implement user authentication
Notes:    Reviewed by Alice    Tested-by: CI Bot <[email protected]>

commit abc1234def567890Author: Developer <[email protected]>Date:   Mon Jan 15 10:00:00 2024 +0000
    feat: implement user authentication
Notes:    Reviewed by Alice    Tested-by: CI Bot <[email protected]>

Append to Notes

bash

# Append to existing note (creates if doesn't exist)git notes append -m "Additional review comment" abc1234
# Append from filegit notes append -F more-comments.txt abc1234
# Append multiple messagesgit notes append -m "Comment 1" -m "Comment 2" abc1234

# Append to existing note (creates if doesn't exist)git notes append -m "Additional review comment" abc1234
# Append from filegit notes append -F more-comments.txt abc1234
# Append multiple messagesgit notes append -m "Comment 1" -m "Comment 2" abc1234

Edit Notes

Remove Notes

bash

# Remove note from HEADgit notes remove
# Remove note from specific commitgit notes remove abc1234
# Remove notes from multiple commitsgit 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

# Remove note from HEADgit notes remove
# Remove note from specific commitgit notes remove abc1234
# Remove notes from multiple commitsgit 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

bash

# Copy note from one commit to anothergit notes copy abc1234 def5678
# Copy note to HEADgit notes copy abc1234
# Force overwrite destination notegit notes copy -f abc1234 def5678
# Bulk copy via stdin (useful with rebase/cherry-pick)echo "abc1234 def5678" | git notes copy --stdin

# Copy note from one commit to anothergit notes copy abc1234 def5678
# Copy note to HEADgit notes copy abc1234
# Force overwrite destination notegit notes copy -f abc1234 def5678
# Bulk copy via stdin (useful with rebase/cherry-pick)echo "abc1234 def5678" | git notes copy --stdin

Prune Notes

bash

# Remove notes for objects that no longer existgit notes prune
# Dry-run to see what would be prunedgit notes prune -n
# Verbose outputgit notes prune -v

# Remove notes for objects that no longer existgit notes prune
# Dry-run to see what would be prunedgit notes prune -n
# Verbose outputgit notes prune -v

Get Notes Reference

Using Multiple Namespaces

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

Specify Notes Ref

bash

# Add note to specific namespacegit 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 namespacegit notes --ref=reviews show abc1234
# List notes in namespacegit notes --ref=reviews list

# Add note to specific namespacegit 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 namespacegit notes --ref=reviews show abc1234
# List notes in namespacegit notes --ref=reviews list

Environment Variable

bash

# Set default notes ref for sessionexport GIT_NOTES_REF=refs/notes/reviewsgit notes add -m "Approved"
# View notes from environment refgit notes show abc1234

# Set default notes ref for sessionexport GIT_NOTES_REF=refs/notes/reviewsgit notes add -m "Approved"
# View notes from environment refgit notes show abc1234

Display Multiple Namespaces

bash

# Show specific notes namespace in loggit log --notes=reviews
# Show multiple namespacesgit log --notes=reviews --notes=testing
# Show all notesgit log --notes='*'
# Disable notes displaygit log --no-notes

# Show specific notes namespace in loggit log --notes=reviews
# Show multiple namespacesgit log --notes=reviews --notes=testing
# Show all notesgit log --notes='*'
# Disable notes displaygit log --no-notes

Merging Notes

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

Merge Notes Refs

bash

# Merge notes from another ref into currentgit notes merge refs/notes/other
# Merge with strategygit notes merge -s union refs/notes/othergit notes merge -s ours refs/notes/othergit notes merge -s theirs refs/notes/othergit notes merge -s cat_sort_uniq refs/notes/other
# Quiet mergegit notes merge -q refs/notes/other
# Verbose mergegit notes merge -v refs/notes/other

# Merge notes from another ref into currentgit notes merge refs/notes/other
# Merge with strategygit notes merge -s union refs/notes/othergit notes merge -s ours refs/notes/othergit notes merge -s theirs refs/notes/othergit notes merge -s cat_sort_uniq refs/notes/other
# Quiet mergegit notes merge -q refs/notes/other
# Verbose mergegit 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

bash

# After merge conflict with manual strategy# Resolve conflicts in .git/NOTES_MERGE_WORKTREE/
# Commit resolved mergegit notes merge --commit
# Abort mergegit notes merge --abort

# After merge conflict with manual strategy# Resolve conflicts in .git/NOTES_MERGE_WORKTREE/
# Commit resolved mergegit notes merge --commit
# Abort mergegit notes merge --abort

Configuration Options

Git Config

bash

# Set default notes refgit config notes.displayRef refs/notes/reviews
# Display multiple notes refsgit config --add notes.displayRef refs/notes/testing
# Set merge strategy for notesgit config notes.mergeStrategy union
# Set merge strategy for specific namespacegit config notes.reviews.mergeStrategy theirs
# Preserve notes during rebasegit config notes.rewrite.rebase true
# Preserve notes during amendgit config notes.rewrite.amend true
# Set rewrite modegit config notes.rewriteMode concatenate

# Set default notes refgit config notes.displayRef refs/notes/reviews
# Display multiple notes refsgit config --add notes.displayRef refs/notes/testing
# Set merge strategy for notesgit config notes.mergeStrategy union
# Set merge strategy for specific namespacegit config notes.reviews.mergeStrategy theirs
# Preserve notes during rebasegit config notes.rewrite.rebase true
# Preserve notes during amendgit config notes.rewrite.amend true
# Set rewrite modegit config notes.rewriteMode concatenate

Sample .gitconfig

gitconfig

[notes]    displayRef = refs/notes/reviews    displayRef = refs/notes/testing    mergeStrategy = union
[notes "reviews"]    mergeStrategy = theirs
[notes.rewrite]    rebase = true    amend = true

[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

# Mark commit as reviewedgit notes --ref=reviews add -m "Reviewed-by: Alice <[email protected]>" abc1234
# Add review commentsgit notes --ref=reviews append -m "Consider extracting helper function" abc1234
# View review statusgit log --notes=reviews --oneline
# Mark as approvedgit notes --ref=reviews add -f -m "APPROVED by Alice" abc1234

# Mark commit as reviewedgit notes --ref=reviews add -m "Reviewed-by: Alice <[email protected]>" abc1234
# Add review commentsgit notes --ref=reviews append -m "Consider extracting helper function" abc1234
# View review statusgit log --notes=reviews --oneline
# Mark as approvedgit notes --ref=reviews add -f -m "APPROVED by Alice" abc1234

Test Results Annotation

bash

# Record test passgit notes --ref=testing add -m "Tests passed: 2024-01-15Platform: Linux x64Coverage: 85%" abc1234
# Record test failuregit notes --ref=testing add -m "FAILED: Integration testsSee: https://ci.example.com/build/123" def5678
# View test status across commitsgit log --notes=testing --oneline

# Record test passgit notes --ref=testing add -m "Tests passed: 2024-01-15Platform: Linux x64Coverage: 85%" abc1234
# Record test failuregit notes --ref=testing add -m "FAILED: Integration testsSee: https://ci.example.com/build/123" def5678
# View test status across commitsgit log --notes=testing --oneline

Audit Trail

bash

# Add audit notegit notes --ref=audit add -m "Security review: PASSEDReviewer: Security TeamDate: 2024-01-15Ticket: SEC-456" abc1234
# Query audit statusgit log --notes=audit --grep="Security review"

# Add audit notegit notes --ref=audit add -m "Security review: PASSEDReviewer: Security TeamDate: 2024-01-15Ticket: SEC-456" abc1234
# Query audit statusgit log --notes=audit --grep="Security review"

Sharing Notes

bash

# Push notes to remotegit push origin refs/notes/reviews
# Fetch notes from remotegit fetch origin refs/notes/reviews:refs/notes/reviews
# Push all notes refsgit push origin 'refs/notes/*'
# Fetch all notes refsgit fetch origin 'refs/notes/*:refs/notes/*'

# Push notes to remotegit push origin refs/notes/reviews
# Fetch notes from remotegit fetch origin refs/notes/reviews:refs/notes/reviews
# Push all notes refsgit push origin 'refs/notes/*'
# Fetch all notes refsgit fetch origin 'refs/notes/*:refs/notes/*'

Bulk Operations

bash

# Add notes to all commits by author in date rangegit 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 commitsgit log --format="%H" HEAD~10..HEAD | xargs git notes remove --ignore-missing

# Add notes to all commits by author in date rangegit 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 commitsgit log --format="%H" HEAD~10..HEAD | xargs git notes remove --ignore-missing

Source and attribution

Source:NeoLabHQ/context-engineering-kitinantigravity/skills/git-notesat commit23e2428

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Git Notes

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

Source and attribution

More from NeoLabHQ/context-engineering-kit

Write Tests

Tree Of Thoughts

Write Concisely

Test Prompt

Update Docs

Test Skill

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices