Description
Git notes are extra blob objects attached to commits via a notes ref (default refs/notes/commits, or core.notesRef / GIT_NOTES_REF). They do not change history; they add metadata Git and other tools can read with git notes.
With no subcommand, grit notes lists every note under the selected ref. show prints one note body to stdout (like git notes show). add writes a new note commit; without --force, adding when a note already exists fails. remove drops notes from the given revisions in a single notes commit when multiple revs are passed.
Notes update commits use your configured user.name / user.email (and optional GIT_* overrides), with the committer date taken from the process clock passed into the library — the same identity rules as grit commit.
Options
| Option | Description |
|---|---|
--ref |
Notes namespace (commits, refs/notes/commits, …). Overrides core.notesRef / GIT_NOTES_REF. |
-n, --limit <N> |
List at most N notes (truncated in JSON when more exist). |
-m, --message |
Note text for add (conflicts with --message-file). |
-F, --message-file |
Read note text from a file, or - for stdin (conflicts with -m). |
--force |
Replace an existing note on add. |
--dry-run |
Preview add or remove without writing objects, refs, or reflogs. |
Subcommands: list, show, add, remove.
JSON output
Schema: v1 (subcommands also have notes.list, notes.show, notes.add, and notes.remove schemas).
Pass --json for stable output. The top-level action field is list, show, add, or remove.
| Field | Type | Meaning |
|---|---|---|
action |
string | list, show, add, or remove. |
notes_ref |
string | Ref that was read or updated. |
notes |
array | For list: object, blob, and body for each note. |
truncated |
boolean | For list: true when more notes exist than returned (-n). |
object |
string | For show / add: annotated commit id (full hex). |
body |
string | For show: note text. |
replaced |
boolean | For add: whether a note was overwritten. |
dry_run |
boolean | For add / remove: true when nothing was written. |
notes_ref_old |
string or null | For add / remove dry-run: notes ref tip before the operation. |
notes_ref_new |
string or null | For add / remove dry-run: predicted notes ref tip after the operation. For remove with several revisions, this is the single notes commit the real run writes; null when no listed revision has a note. |
note_blob |
string or null | For add dry-run: blob id that would store the note bytes. |
objects |
array | For remove: ids whose notes were removed (or would be, with --dry-run), in argument order. Revisions without a note and repeats are left out. |
Markdown output
Pass --markdown for agent-friendly output.
Schema: v1
List actions render a heading with the notes ref and one bullet per note (short object id and body preview). Show wraps the note body in a fenced text block. Add and remove print a short confirmation line per action; with --dry-run it starts with "Would" (for example Would remove notes on `refs/notes/commits`:).
Exit status
See Exit codes for shared rules and structured --json kind values.