Annotating Commits with git notes: Metadata Without Rewriting History

Every so often a commit needs a footnote. The reviewer found something worth remembering. The ticket reference went missing. A benchmark run proved the change was worth it. The message is already written and pushed, though - and rewriting pushed history is a bad trade for a footnote.

git notes is the feature for exactly this: annotations that attach to a commit without changing the commit.

The basics#

git notes add -m "Reviewed in PR #412, follow-up filed as BILL-88" HEAD
git log --show-notes

The note shows up in git log output under the commit message. The commit hash does not change - the note lives in a separate ref (refs/notes/commits), so nothing is rewritten and nobody else’s clone breaks.

Notes do not push by default, which surprises everyone once:

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

Share them by pushing the notes ref; teammates fetch it explicitly. It is one extra step, once, per clone.

What Laravel teams actually use them for#

• Linking commits to review. A note with the pull request URL makes git blame and history archaeology richer months later, without touching the original message.
• Recording verification. “Deployed to staging 2026-10-20, smoke tests green” - evidence attached to the exact commit it concerns.
• Explaining the weird one. The commit that looks wrong but is deliberate gets a note saying why, so the next person does not “fix” it.

The honest limits#

Notes are the right size for footnotes, not documentation. They are easy to forget (out of git log unless you ask), awkward to merge when two people annotate the same commit, and invisible on most web UIs - GitHub shows them in the API but not prominently in the interface. If the information matters to everyone every day, put it in the commit message or the changelog instead.

Reach for notes when the annotation is valuable to the future archaeologist and not worth a history rewrite: that is a real niche, and nothing else in Git fills it as cleanly.