gritHEAD → docs/notes
Commands / HistoryMarkdown

grit notes

List, show, add, and remove Git notes on commits.

grit notes [--ref REF]
grit notes list [--ref REF]
grit notes show <rev> [--ref REF]
grit notes add <rev> (-m <message> | -F / --message-file <path|->) [--force] [--dry-run] [--ref REF]
grit notes remove <rev>... [--dry-run] [--ref REF]

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

Code Meaning
0 Success (success).
1 Command failed (failure).
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.