Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Inspecting History

git notes command

Reference for git notes: add, append, show, list, edit, copy, merge and remove notes on commits and other objects without changing their hashes, and share them.

A note is a piece of text attached to an object, usually a commit, without changing that object. Because a commit's hash covers its message, you cannot edit the message later without rewriting history. Notes solve this: they live in a separate ref (refs/notes/commits by default) and are looked up by the hash of the object they annotate.

Typical uses: review sign-offs, CI results, bug tracker IDs and migration remarks added after the fact. git log shows notes under the message automatically.

Terminal
git notes [list [<object>]]
git notes add [-f] [-m <msg> | -F <file>] [<object>]
git notes append | edit | show | remove | copy | merge | prune
git notes [--ref <ref>] <subcommand>

Try it

Bash Add, append and show notes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Notes are not pushed by default

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Subcommands (the object defaults to HEAD):

Subcommand Description
list [<object>] Print <note blob> <object> pairs, or just the note blob for one object.
add [-f] [-m <msg>] [-F <file>] [<object>] Create a note. Fails if one exists unless -f (overwrite). -m can repeat; each becomes a paragraph.
append [-m ...] [<object>] Add a paragraph to the existing note (or create it).
edit [<object>] Open the note in your editor.
show [<object>] Print the note; exit status 1 if there is none.
remove [<object>...] Delete notes. --ignore-missing hides errors.
copy <from> <to> Copy a note to another object (--stdin copies many; used by rewrites).
merge <ref> Merge another notes ref; -s manual|ours|theirs|union|cat_sort_uniq picks a strategy.
prune Delete notes whose object no longer exists.

Select a namespace with --ref=<name> (stored in refs/notes/<name>) or the GIT_NOTES_REF variable; git log --notes=<name> and --show-notes=<ref> display other namespaces, and --no-notes hides them. The pretty-format placeholder %N expands to the note text.

Usage notes

  • Notes are not transferred by git push, git fetch or git clone. Push and fetch refs/notes/* explicitly, or add a refspec such as remote.origin.fetch = +refs/notes/*:refs/notes/*. Hosting sites usually do not display them.
  • Notes are keyed by full hash. After rebase or commit --amend the new commits have new hashes and the notes do not follow unless you set notes.rewriteRef (for example to refs/notes/commits); then rewrites copy notes automatically. notes.rewrite.rebase and notes.rewrite.amend default to true.
  • Each change to a notes ref is itself a commit in that ref; the history of your annotations is preserved.
  • Notes can be attached to any object (a blob or tag too), but commits are by far the common case.
  • Conflicts arise when two people annotate the same commit and then merge their notes refs; choose a merge strategy such as union.
  • git notes list outputs the note's blob hash first and the annotated object second, which surprises scripts.