git notes

A side-channel for things that don't belong in the commit message.

🎯 What & why

Attach metadata to a commit without changing the commit. Useful for review notes, build IDs, or any annotation you don't want bleeding into the message itself.

🧠 Mental model

Notes live in a separate ref (default refs/notes/commits). Each note is a blob keyed by the commit's SHA. They don't affect the commit's SHA at all. They have their own remote-tracking dance — they don't push or fetch by default.

🛠️ Synopsis

git notes [list [<object>]]
git notes add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
git notes copy [-f] (--stdin | <from-object> [<to-object>])
git notes append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
git notes edit [--allow-empty] [<object>] [--allow-empty]
git notes show [<object>]
git notes merge [-v | -q] [-s <strategy>] <notes-ref>
git notes merge --commit [-v | -q]
git notes merge --abort [-v | -q]
git notes remove [--ignore-missing] [--stdin] [<object>...]
git notes prune [-n] [-v]
git notes get-ref

🎚️ Switches & options

Flag	What it does
`add -m "<msg>"`	Add a note to a commit.
`show <commit>`	Show the note for a commit.
`edit <commit>`	Edit the note in $EDITOR.
`remove <commit>`	Delete the note.
`--ref=<name>`	Use a different notes namespace.

📦 Subcommands

add [-m <msg>] [<commit>] — Add a note to a commit.

$ git notes add -m 'rev: looks good' HEAD~1

show [<commit>] — Display the note for a commit.

$ git notes show HEAD~1

edit [<commit>] — Edit a note in $EDITOR.

$ git notes edit HEAD~1

append -m <msg> [<commit>] — Append to an existing note.

$ git notes append -m 'second pass: still good' HEAD~1

remove [<commit>] — Delete a note.

$ git notes remove HEAD~1

list [<commit>] — List all notes (or the SHA of one commit's note).

$ git notes list

merge <notes-ref> — Merge another notes namespace into the current one.

$ git notes merge refs/notes/upstream

prune — Remove notes for commits that no longer exist.

$ git notes prune

💡 Use cases

Review comments without touching the commit message.
Build IDs / external references.
Lightweight workflow metadata.

🧪 Examples

Annotate a commit.

$ git notes add -m 'rev: looks good, ship it' HEAD~1

Show notes alongside log.

$ git log --show-notes

Push notes to remote.

$ git push origin refs/notes/commits

🎓 Recommendations

Notes are a side-channel. Don't put critical information in them — most tooling doesn't surface them.
If you push notes, document it. They don't travel by default.