git notes — Annotations outside the Tree

git notes — Annotations outside the Tree

Thesis

git notes attach free-form text to an object (usually a commit) without changing its hash. Review commentary, CI URLs, and backport hints can ride along without rewriting history.

Mental model

  commit abc123  ←── notes/commits → "Reviewed-by: …"
  (tree unchanged; notes live in refs/notes/*)

Default ref: refs/notes/commits. Fetch/push notes explicitly — they are not part of ordinary branch fetch unless configured.

Worked example

# lab identity already set for this demo
git notes add -m "lab note: verified on box" HEAD
git notes show HEAD
git log -1 --notes
git notes remove HEAD   # cleanup when done

=== notes show ===
review: LGTM after nits
=== log --notes ===
8a2c39b add f
Notes:
    review: LGTM after nits

Sharing:

git push origin refs/notes/commits
git fetch origin refs/notes/commits:refs/notes/commits

Trap

Expecting notes to clone by default. They will not. Also: amending a commit changes its OID — notes stay on the old OID unless rewritten. Notes are the wrong tool for signed release metadata that must be immutable and always-present; use tags or the commit message for that.

Boring rule

Use notes for optional, discardable annotations. Document the notes ref in the repo README if the team relies on them, and add an explicit fetch refspec.

Try this

1. Add a note, git commit --amend, and observe the note no longer shows on HEAD.
2. Configure fetch = +refs/notes/*:refs/notes/* in a test remote.
3. Compare notes vs git interpret-trailers in commit messages.

Sources

• git notes documentation
• Git Book: notes appendix material / plumbing refs/notes