git notes: Annotating Commits Without Rewriting History

git notes lets you attach arbitrary text to any commit without rewriting history — useful for adding deployment records, code-review comments, or CI results to commits on a WordPress project after the fact.

Problem: A commit needs additional context — a Jira ticket link, a post-deploy observation, a reviewer note — but amending the commit would rewrite history on a shared branch, and commit messages cannot be changed after pushing.

Solution: Use git notes to attach arbitrary text to any commit without modifying its hash. Notes are stored separately from the commit object, can be pushed and fetched explicitly with git push origin refs/notes/commits, and are visible in git log --notes.

The examples below add and read notes, push and fetch notes to/from a remote, and use notes namespaces to separate deployment logs from review comments.

# Add a note to the latest commit
git notes add -m "Deployed to staging at 2024-06-03 14:22 UTC by @jane"

# Add a note to a specific commit
git notes add -m "Reviewed by @bob — approved" abc1234

# View notes in git log
git log --show-notes

# Read the note for a specific commit
git notes show abc1234

# Append to an existing note (instead of replacing it)
git notes append -m "Also tested on PHP 8.2" abc1234

# Edit a note in your $EDITOR
git notes edit abc1234

# Remove a note
git notes remove abc1234

Use namespaced notes to keep deployment and review notes separate, and push them to remotes:

# Notes live in refs/notes/commits by default.
# Use namespaces (separate refs) for different note types:

# Write a deployment note in a custom namespace
git notes --ref=refs/notes/deployments add -m "Production deploy: v2.3.1 — 2024-06-03" HEAD

# Write a CI result note
git notes --ref=refs/notes/ci add -m "PHPUnit: 143/143 passed. PHPStan: 0 errors." HEAD

# Push notes to origin (not pushed by default!)
git push origin refs/notes/commits
git push origin refs/notes/deployments
git push origin refs/notes/ci

# Fetch notes from remote
git fetch origin refs/notes/*:refs/notes/*

# Configure git to always push/fetch notes automatically
# .git/config or ~/.gitconfig:
# [remote "origin"]
#     fetch = +refs/notes/*:refs/notes/*
#     push  = refs/notes/*

# Show notes from a specific namespace in log
git log --notes=deployments --oneline -10

NOTE: Notes are stored as separate objects in the Git object database and do not affect commit hashes — making them safe to add even to public, shared branches where rewriting history is not allowed.