Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 78 ยท Customizing and Automating Git

Git Notes

Learn git notes: add, show, edit and remove notes on commits without changing hashes, use namespaces, display notes in git log, push them and merge them.

A commit's message is part of the commit. Change one letter and the commit gets a new hash. That is a problem when you want to add information after the commit exists: a code review link, a build result, a ticket number you forgot, or a reminder about why a commit was safe to ship. Rewriting history to fix a message on a shared branch is exactly what you want to avoid.

Git notes solve this. A note is extra text attached to a commit (or any object) and stored separately, so the commit and its hash stay exactly the same. In this lesson you will add, view, edit and remove notes, use separate namespaces, see how notes appear in git log, and learn how to share them, because notes are not pushed by default.

How notes are stored

Notes live in their own ref, refs/notes/commits by default. That ref points to a normal commit whose tree maps object names to note blobs. In other words, the notes are themselves versioned by Git.

flowchart LR
  C["Commit 3f2a1b<br/>(unchanged)"]
  R["refs/notes/commits"] --> N["Notes commit"]
  N --> T["Notes tree<br/>3f2a1b... -> blob"]
  T --> B["Blob: 'Reviewed by Grace'"]
  T -.names.-> C

A note is a blob in a separate tree, keyed by the hash of the commit it describes.

Adding and showing a note

git notes add -m attaches a note to HEAD (or to any commit you name). git notes show prints it, and git log displays notes automatically underneath the message.

Bash Add, show and list notes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The two hash lines are identical: adding a note did not rewrite the commit. git log printed the message followed by a Notes: block with the text. The new ref refs/notes/commits exists, and git notes list has one entry per annotated commit.

Because each note change creates a new commit on the notes ref, you can see the note history with git log refs/notes/commits. Notes are never lost by simply editing them.

Editing, appending and removing

You can attach a note to an older commit by naming it. If the commit already has a note, add refuses unless you pass -f. Use append to add a paragraph instead, and remove to delete.

Bash Append, overwrite and remove

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

add on a commit that already has a note stops with an error mentioning "Cannot add notes", and -f replaces it. append joins the new text after a blank line. After remove, git notes show fails with "no note found". Run git notes edit (no -m) to open the note in your editor instead.

Namespaces with --ref

The default notes ref is shared by everyone who uses plain git notes. For a specific purpose, such as build results, give the notes their own namespace with --ref. Git stores them in refs/notes/<name>. Separate namespaces keep unrelated tools from overwriting each other's notes, and you can share only the ones you want.

Bash Two namespaces on one commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The two refs are refs/notes/ci and refs/notes/commits. A plain git log only displays refs/notes/commits unless you name another namespace with --notes=<name>. You can pass several. The format placeholder %N prints the notes in a custom --format, which is how scripts read them.

You can also tell Git which extra namespaces to always show in git log with git config notes.displayRef 'refs/notes/ci', and which one git notes uses by default with core.notesRef.

Notes are not pushed by default

This is the part that surprises people. git push and git fetch only transfer branches and tags, not refs/notes/*. A note you made stays in your repository until you push its ref explicitly. A teammate has to fetch it explicitly, too.

CONSOLE
git push origin refs/notes/commits
git fetch origin refs/notes/commits:refs/notes/commits

To make it automatic, add a refspec to the remote's configuration:

CONSOLE
git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'
git config --add remote.origin.push 'refs/notes/*'

The next example uses a local bare repository as the "remote" to prove it.

Bash Notes travel only when you push the ref

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bob's clone has zero notes even though Alice's last git push succeeded. Only after Alice pushed refs/notes/commits and Bob fetched it into his own refs/notes/commits did Bob see the text. This is also why notes are a poor way to store information the whole team must see: someone will forget the refspec. Use them for supporting data, not for rules.

Merging notes and rewriting history

If two people add notes to the same commit in different clones, fetching into the same ref produces a conflict-like situation. git notes merge <ref> merges another notes ref into yours, with strategies such as union (keep both texts), ours and theirs:

CONSOLE
git fetch origin refs/notes/commits:refs/notes/origin
git notes merge -s union refs/notes/origin

Notes follow the commit hash, so when you rewrite history (rebase, amend, filter) the new commits have new hashes and the old notes no longer apply. Two settings copy notes across rewrites:

CONSOLE
git config notes.rewriteRef refs/notes/commits

With that set, git commit --amend and git rebase copy the note to the new commit. You can also copy by hand with git notes copy <from> <to>. See Rebase and Amend and Filter for how hashes change.

When to use notes

Good fits: a link to the code review or build for a commit, test results, a "backported to release-2.1" marker, and later corrections ("this commit actually fixes TICKET-17") on already-published history. Poor fits: anything people must always see (put it in the commit message or the pull request), and anything needing a reliable sync story. Hosting platforms such as GitHub do not display notes in their web interface, so treat them as a local and tooling feature. Compare with tags, which are named, pushed explicitly and attached to one commit each.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to a commit's hash when you add a note to it with git notes add?

    Notes are stored in refs/notes/... as blobs keyed by the commit hash. The commit object itself is untouched.
  2. 2. A teammate pulls your branch but cannot see your notes. Why?

    You must push refs/notes/commits and the teammate must fetch it, or configure refspecs so it happens automatically.
  3. 3. How do you show notes from a namespace called ci in git log?

    --notes=<name> tells git log to display refs/notes/<name>. Without it, only the default refs/notes/commits is shown.
  4. 4. You amend a commit that has a note. What happens to the note by default?

    The amended commit has a new hash, and notes are keyed by hash. Configure notes.rewriteRef or copy the note with git notes copy.

Summary

  • A note is text attached to a commit and stored in refs/notes/commits; the commit hash does not change.
  • Use git notes add, show, append, edit and remove; add -f overwrites. git log shows notes under the message.
  • --ref=<name> creates a separate namespace; show it with git log --notes=<name>.
  • Notes are not pushed or fetched by default. Transfer refs/notes/* explicitly or add refspecs.
  • git notes merge -s union combines notes from two sources; notes.rewriteRef carries notes across amend and rebase.
  • Use notes for supporting information, not for anything everyone must see.

Next: Git LFS Workflows