Notes

Git notes are auxiliary commits under refs/notes/*. The notes module defines NotesRef (for example NotesRef::commits, or NotesRef::parse for a short name like review), tree helpers, and resolve_configured_notes_ref for GIT_NOTES_REF / core.notesRef.

Repository::notes exposes RepositoryNotes:

• add attaches a note and returns a NoteAddOutcome (Added or Replaced). Without force, an existing note is Error::NoteAlreadyExists. The content bytes are stored as given.
• read returns one note's bytes, list returns (object, note blob) pairs as NoteListing, and list_with_bodies returns every Note with its contents, sorted by object. A missing or non-blob note object is an error, never an empty note.
• remove_many removes several notes in one notes commit.
• plan_add and plan_remove_many preview a write without touching objects, refs, or reflogs. NoteAddPlan and NoteRemoveManyPlan report the notes ref tip before the write and the notes commit the write would create. A batch plan applies every removal to one tree, so its predicted tip is the commit remove_many writes for the same objects and options.

Writes take an explicit committer and optional author (Signature values, usually from repo.identity) and a commit message through NotesWriteOptions. Each write is one notes commit on top of the tip the existing notes were read from. The ref moves through the repository's ref store as a compare-and-swap update from that same tip, so it works the same on loose/packed refs, reftable, or an injected MemoryRefStore, and an add or remove_many that races another notes writer fails instead of dropping the other writer's note. The lower-level write_notes_commit replaces the whole tree with the entries you pass, so callers that read entries themselves own that race. The reflog line (notes: <message>) is written in the same transaction whenever the ref already has a reflog or core.logAllRefUpdates allows creating one.

A notes ref that points at something other than a notes commit or tree fails with Error::NotesRefNotCommit, and a malformed notes tree fails with Error::NotesObjectKind.