git-notes

List all notes and the objects they are attached to

$ git notes list

$ git notes list [[object]]

$ git notes show [[object]]

$ git notes append [object]

$ git notes append --message="[message_text]"

$ git notes edit [[object]]

$ git notes copy [source_object] [target_object]

$ git notes remove [object]

git notes [--ref <name>] [--stdin] (list [<object>] | add [-f] [-m <msg> | -F <file> | -c <oid> | -C <oid>] [<object>] | append [-f] [-m <msg> | -F <file> | -c <oid> | -C <oid>] [<object>] | copy [-f] <from-object> <to-object> | edit [<object>] | show [<object>] | merge [-v | -q] [-s <strategy>] [<notes-ref>] | merge --commit [-v] | merge --abort | prune [-n | -v] | get-ref)

--ref <name>
    Use notes ref <name> (e.g., refs/notes/commits) instead of default.

--stdin
    Read objects or pairs from stdin (for list, prune, add, append, copy).

list [<object>]
    List notes for given object or show ref if no object.

add [-f] [-m <msg> | -F <file> | -c/-C <oid>] [<object>]
    Add note for object; -f forces overwrite; -m/-F for message/file; -c/-C reuse/edit existing note.

append [-f] [-m/-F/-c/-C]
    Append note reusing existing one if present.

copy [-f] <from> <to>
    Copy note from one object to another; -f forces.

edit [<object>]
    Edit note for object using $EDITOR.

show [<object>]
    Display note for object.

merge [-v|-q] [-s <strategy>] [<notes-ref>]
    Merge notes ref; strategies: cat_sort_uniq, theirs, ours, union, manual_3way.

merge --commit [-v]
    Finalize in-progress merge by committing.

merge --abort
    Abort in-progress merge.

prune [-n|-v]
    Remove notes for unreachable objects; -n dry-run, -v verbose.

get-ref
    Print current notes ref name.

git notes enables attaching arbitrary notes to Git objects such as commits, trees, blobs, or tags without modifying the objects themselves. Notes are stored in a separate Git tree object under a notes reference (default: refs/notes/commits), preserving the integrity of the original data.

This feature is ideal for adding metadata like code review comments, performance benchmarks, test results, or blame annotations that should not alter commit history. Notes can be displayed inline with commands like git log, git show, or git diff using the --notes option or by configuring core.notesRef.

Notes support multiple refs for different purposes (e.g., refs/notes/commits, refs/notes/tags). Changes to notes are tracked via reflog, allowing history of modifications. Merging notes refs is supported with strategies like theirs, ours, union, or cat_sort_uniq.

By default, notes are not pushed or fetched; use push --notes or config notes.displayRef for integration. Pruning removes notes for unreachable objects, aiding repository maintenance.

Notes are not pushed/pulled by default; use git push --notes or remote.<name>.push = refs/notes/*:refs/notes/*. No automatic cleanup of dangling notes.

Set notes.displayRef = refs/notes/* to auto-show notes in log/show; use git log --notes=<ref>.

git notes add -m "Fixes bug #123" HEAD
git log --oneline --notes

Introduced in Git 1.6.3 (October 2009) by Johannes Schindelin. Multiple notes refs added in 1.6.6; merge support in 1.7.0; prune enhancements in later versions. Widely used for CI annotations and code reviews.

git-log(1), git-show(1), git-config(1), git-merge(1), git-reflog(1)