git notes

Inspection & Comparison

Attach notes to commits without changing them


The 'git notes' command attaches extra text to a commit — a review, a test result, a deployment date — without touching the commit itself, so its hash stays the same. Notes are stored separately (in refs/notes/commits) and git log shows them under the commit message. They are not pushed or fetched by default.

Synopsis

git notes [list [<object>]]
git notes add [-f] [-m <msg>] [<object>]
git notes append [-m <msg>] [<object>]
git notes show [<object>]
git notes remove [<object>...]
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (4)

Add text to the existing note (or create one).

RecommendedAdd information without losing the existing note

Example

git notes append -m "Tests pass"

Print the note of a commit (HEAD by default).

RecommendedRead one commit’s note

Example

git notes show HEAD~1

List every note: the note id and the commit it belongs to.

When neededFind every commit that has a note

Example

git notes list

Delete the note of a commit.

When neededRemove an outdated note

Example

git notes remove

Choosing the Right Option

Adding information to a commit

Note or amend?

CommandHash changes?Safe after push?
git commit --amendYesNo
git notes addNoYes

Examples

Add a note

git notes add -m "Reviewed by Sam"

Attach a note to HEAD.


Note an older commit

git notes add -m "Deployed" a1b2c3d

Any commit can get a note.


Share notes

git push origin refs/notes/commits

Notes are only pushed when you ask.

Workflow Examples

1
git notes add -m "Reviewed by Sam" a1b2c3d

Attach the note

2
git push origin refs/notes/commits

Share it with the team

Troubleshooting

error: Cannot add notes. Found existing notes

Cause: The commit already has a note

Use git notes append, or add -f to replace it

Teammates do not see my notes

Cause: Notes are not pushed by default

git push origin refs/notes/*, and fetch them with git fetch origin refs/notes/*:refs/notes/*

Tips & Pitfalls

Best Practices

  • ✓Use notes for information that comes after the commit (reviews, CI results).

Common Mistakes

  • ✗Amending a pushed commit just to add information — a note keeps the hash.
  • ✗Expecting notes to travel with git push — push refs/notes/* explicitly.

FAQ

A:

No. They are stored beside it; the commit and its hash stay identical.