git notes: Usage, Options & Common CI Errors
git notes attaches extra information to a commit without rewriting it.
Notes let CI annotate commits (build IDs, review links) out of band, since they are stored separately under refs/notes.
What it does
git notes stores annotations in a separate refs/notes namespace and binds them to commits, so you can add metadata without altering the commit object or its SHA.
Common usage
Terminal
git notes add -m "build: 1234" <sha>
git notes show <sha>
git notes append -m "deployed" <sha>
git push origin refs/notes/commits # notes are not pushed by default
git fetch origin refs/notes/*:refs/notes/*Options
| Subcommand / flag | What it does |
|---|---|
| add -m <msg> | Attach a note to a commit |
| show | Display a commit’s note |
| append | Add to an existing note |
| remove | Delete a note |
| --ref <name> | Use a non-default notes ref |
Common errors in CI
error: Cannot add notes. Found existing notes for object … Use '-f' to overwrite - a note already exists; pass -f or use append. Notes are not transferred by default, so remote tooling sees nothing until you push refs/notes/* explicitly.
Related guides
git log: Usage, Options & Common CI Errorsgit log shows commit history with flexible formatting. Reference for --oneline, --graph, --pretty, ranges, an…
git show: Usage, Options & Common CI Errorsgit show displays a commit, tag, or object with its diff. Reference for --stat, --name-only, blob viewing, an…
git push: Usage, Options & Common CI Errorsgit push uploads local commits to a remote. Reference for -u, --force-with-lease, and tags, plus the rejected…
git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh…