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.
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
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.
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 fetchorgit clone. Push and fetchrefs/notes/*explicitly, or add a refspec such asremote.origin.fetch = +refs/notes/*:refs/notes/*. Hosting sites usually do not display them. - Notes are keyed by full hash. After
rebaseorcommit --amendthe new commits have new hashes and the notes do not follow unless you setnotes.rewriteRef(for example torefs/notes/commits); then rewrites copy notes automatically.notes.rewrite.rebaseandnotes.rewrite.amenddefault 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 listoutputs the note's blob hash first and the annotated object second, which surprises scripts.
Related
- git log, git log format, git push, git fetch
- Tutorial: Git notes