Skip to content

Git Notes — Quick Reference

Annotate commits with CI/CD metadata (build IDs, coverage, deployment info) without changing commit SHAs.

Add / Edit / Remove

git notes add -m "ci: build #4821 passed" HEAD         # add note to HEAD
git notes add <SHA> -m "security-scan: clean"          # add to specific commit
git notes append <SHA> -m "extra: detail here"         # append (don't replace)
git notes edit <SHA>                                   # edit interactively
git notes remove <SHA>                                 # remove a note
git notes show                                          # show note on HEAD
git notes show <SHA>                                    # show note on SHA
git notes list                                          # list all notes

Named Namespaces

git notes --ref=ci       add -m "..." HEAD
git notes --ref=security add -m "..." HEAD
git notes --ref=deploy   add -m "..." HEAD

git config notes.ref "ci"     # change the default notes ref globally

Push / Fetch

# Push (notes are NEVER included in normal `git push`)
git push origin refs/notes/ci
git push origin 'refs/notes/*'                  # all notes refs

# Fetch in CI (shallow clones)
git fetch origin refs/notes/ci:refs/notes/ci
git fetch origin +refs/notes/*:refs/notes/*     # all notes refs

Copy Notes on Rebase

# After rebase, migrate notes from old SHAs to new SHAs
git rebase --onto new-branch old-branch
# Manually copy if notes lost:
git notes copy <OLD_SHA> <NEW_SHA>

# Auto-copy: add to .git/config or use post-rebase hook
git config --add notes.rewrite.rebase true       # copy notes during rebase
git config --add notes.rewrite.create false      # don't auto-create

Query Notes

# Show log with notes inline (custom displayRef)
git config notes.displayRef "refs/notes/ci"
git log --format='%h %s%n  CI: %N'

# Iterate recent commits and show their CI notes
git log --format='%H' -20 | while read sha; do
  note=$(git notes --ref=ci show "$sha" 2>/dev/null) && echo "$sha $note"
done

CI/CD Pattern (Single Liner)

git config user.email "ci@bots" && \
git config user.name  "CI Bot"  && \
git notes --ref=ci append HEAD \
  -m "pipeline=$BUILD coverage=$COVERAGE status=pass ts=$(date -u +%I%M%S)" && \
git push origin refs/notes/ci

Gotchas

  • Notes are NOT included in normal git push / git fetch
  • Default ref is refs/notes/commits — pick a named ref to avoid clutter
  • Notes are SHA-tied — rebase orphans them; enable notes.rewrite.rebase or git notes copy
  • Shallow CI clones need an explicit git fetch origin refs/notes/<ref> step
  • Notes refs are themselves commits — they live in .git/refs/notes/