Notes without rewriting

git notes attaches arbitrary metadata to existing commits without changing their SHAs. Reviews, build statuses, sign-offs, performance metrics — anything you want associated with a commit can live in notes. They are stored in the special ref refs/notes/commits by default.

Adding and editing

git notes add -m "Reviewed by team Phoenix" <sha>
git notes append -m "QA passed" <sha>
git notes edit <sha>
git notes show <sha>
git notes remove <sha>

Using namespaces

Notes can live under multiple refs, one per "channel":

git notes --ref=builds add -m "build #1234 OK" <sha>
git notes --ref=reviews add -m "LGTM" <sha>
git config notes.displayRef "refs/notes/*"

notes.displayRef tells git log which note refs to show.

Showing in log

git log --notes
git log --show-notes=builds
git log --pretty=format:'%h %s%n%N' --notes

The %N placeholder expands to all visible notes for that commit.

Sharing notes

Notes refs are not fetched by default. Configure explicit fetch refspecs:

git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'
git fetch
git push origin 'refs/notes/*'

Use case: CI annotations

A CI system can post results back as notes:

git notes --ref=ci add -m "duration=312s status=pass coverage=87%" <sha>
git push origin refs/notes/ci

Developers fetch the notes channel to see results inline with git log.

Merging notes

If two collaborators add notes to the same commit on different clones, fetching one over the other may conflict. Resolve with:

git notes merge -s union refs/notes/origin/commits

Strategies: manual (default), ours, theirs, union, cat_sort_uniq.

Common mistakes

Expecting notes to travel with git push automatically — they do not. Configure refspecs explicitly. Believing notes are immutable like commits; they are versioned in their own ref but rewritable. Putting confidential data in notes — they share the repo's distribution model.

Related

See "Advanced git log: formatting, filtering, and graph" and "Git internals: references and the reflog".