Git Notes: Attach Metadata to Git Objects

Advanced

What Git notes are

A Git note is additional text associated with an object, commonly a commit. The note is stored separately from the object, so adding or changing a note does not change the commit ID. By default Git reads and writes notes through refs/notes/commits. Notes can therefore carry review context, test results, or other annotations without rewriting the commit itself.

git notes add -m "reviewed" HEAD
git notes show HEAD
git notes list HEAD
git notes get-ref

Add, replace, append, and edit notes

`git notes add` creates a note and refuses to replace an existing note unless `-f` is used. `append` adds to an existing note instead of replacing it. `-m` supplies the text directly, while `-F` reads it from a file. `edit` opens the note for editing; unlike `add -m`, it is editor-driven unless content is supplied through the editor environment.

git notes add -m "review: verified" HEAD
git notes add -f -m "review: rechecked" HEAD
git notes append -m "second observation" HEAD
printf '%s\n' 'test evidence' > note.txt
git notes add -F note.txt HEAD
# Edit the existing note with your configured editor.
git notes edit HEAD

Read and identify notes

`show` displays the note attached to an object. `list` can show the note object and annotated object, while `get-ref` prints the notes ref currently in use. These are useful when scripts or diagnostics need to distinguish the annotation from the object it annotates.

git notes show HEAD
git notes list HEAD
git notes list
git notes get-ref
git log --show-notes --oneline -1

Copy and remove notes

`copy` transfers the note from one object to another. By default it refuses to overwrite an existing destination note; `-f` allows replacement. The `--stdin` form accepts source and destination object IDs from standard input. `remove` deletes notes, and its `--stdin` form accepts object IDs to remove.

git notes copy HEAD HEAD~1
git notes copy -f HEAD HEAD~1
printf '%s %s\n' HEAD HEAD~2 | git notes copy --stdin
git notes remove HEAD~1
printf '%s\n' HEAD~2 | git notes remove --stdin

Custom notes refs

Notes are refs, not fields inside the annotated commit. Git normally uses `refs/notes/commits`, but a different notes ref can be selected with the notes-ref configuration. Separate refs can therefore hold separate annotation sets. When demonstrating or scripting custom refs, keep the ref name explicit so readers know which note set they are inspecting.

git -c core.notesRef=refs/notes/review notes add -m "review annotation" HEAD
git -c core.notesRef=refs/notes/review notes show HEAD
git -c core.notesRef=refs/notes/review notes get-ref

Merge notes

`git notes merge <notes-ref>` merges another notes ref into the current notes ref. Notes conflicts can require a resolution in Git's notes merge worktree; the official workflow provides `git notes merge --commit` to finish and `git notes merge --abort` to abandon the merge. The merge operates on note refs, not on the annotated commits themselves.

git notes merge refs/notes/review
git notes merge --commit
git notes merge --abort

Prune unreachable notes

A note can become unnecessary when the object it annotates is no longer reachable. `git notes prune` removes notes for non-existing or unreachable objects. `-n` performs a dry run, making it the safer inspection form before an actual cleanup.

git notes prune -n
git notes prune

Notes and rewritten commits

Because notes annotate objects by object name, rewriting a commit creates a different object name. Git provides notes-rewrite configuration so selected rewriting commands can carry notes across rewritten commits. That is a separate mechanism from manually copying a note and should not be confused with changing the original commit.

A disciplined notes workflow

First decide what object the annotation belongs to. Add a note with an explicit message, inspect it, and use `append` when preserving existing text matters. Use a dedicated notes ref when separate annotation sets need independent visibility. Before destructive cleanup, run `prune -n`. Treat notes as shared Git data that may need explicit transport/configuration; do not assume that pushing the ordinary branch automatically communicates every notes ref.

git notes add -m "CI: verified on Linux" HEAD
git notes show HEAD
git notes append -m "CI: integration suite passed" HEAD
git notes get-ref
git notes prune -n

What git notes does not own

This lesson does not replace `git commit --amend` or other commit-message workflows: a note does not modify the commit message. It does not replace `git tag`, which names objects through refs with tag semantics. It does not replace `git range-diff`, which compares commit series. It does not replace ordinary ref manipulation, and it does not make notes part of the commit object itself.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official source boundary

This lesson uses the official Git git-notes documentation for command semantics and the official Git command documentation for notes integration. No third-party documentation is used for Git command semantics.