patterngitTip

git notes: attach metadata to commits without changing their SHA

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

git notescommit metadataattach notesnotes pushnon-destructive annotation

Error Messages

error: Cannot add notes. Found existing notes for object a1b2c3d. Use '-f' to overwrite existing notes

Problem

You need to attach build status, review notes, or deployment metadata to a commit, but amending the commit would change its SHA and break references.

Solution

Use git notes to attach metadata without altering the commit:

# Add a note to the current commit
git notes add -m "Deployed to production: 2024-03-15 14:30 UTC"

# Add a note to a specific commit
git notes add -m "Build #1234 passed" a1b2c3d

# Show notes in git log
git log --show-notes

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

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

Why

Git notes are stored as separate objects referenced from the commit but not as part of the commit. The commit SHA doesn't change. Notes are stored in refs/notes/ and must be explicitly pushed and fetched.

Gotchas

Notes are NOT pushed or fetched by default — you must explicitly configure the refspec
Notes are not preserved by git rebase — rebased commits lose their notes
GitHub and GitLab do not display git notes in their web UIs

Code Snippets

Using git notes for deployment metadata

# Add a deployment note
git notes add -m "Deployed to prod: $(date -u)" HEAD

# View notes in log
git log --show-notes=commits -1

# Push notes to remote
git push origin refs/notes/commits

# Auto-fetch notes
git config --add remote.origin.fetch '+refs/notes/commits:refs/notes/commits'
git fetch origin

Context

CI systems or deployment pipelines that need to annotate commits with build/deploy metadata

Revisions (0)

No revisions yet.