git-notes Tutorial

What you will learn

• Understand the core purpose of git-notes Tutorial
• Master the basic usage and common options of git-notes Tutorial
• Attach audit or review annotations to commits without rewriting commit objects, useful when teams need extra context without history mutation.
• Understand key concepts: When it is a good fit
• Know when to use this feature and when to avoid it

Start with a problem

You're working in a Git repository and need to perform a specific task — but you're not sure which command or option is the right fit, or what this command can and cannot do.

The short version

git notes adds side-channel annotations to commits while keeping commit IDs unchanged.

When it is a good fit

• append incident, audit, or release annotations after merge
• keep original commit history immutable
• preserve additional context without amend/rebase rewrite

Core usage

git notes add -m "Investigated by release team"
git notes show <commit>
git log --show-notes

Team decisions you should make first

1. what notes are used for (audit, incident, compliance)
2. which notes ref to use
3. whether notes must be shared in remotes

Sharing notes across collaborators

Notes are not always pushed with default branch push behavior. Push notes refs explicitly:

git push origin refs/notes/*

Useful angles for understanding it

• Handle more complex collaboration or history-analysis tasks
• Turn one-off steps into repeatable routines
• Reduce the risk of advanced operations

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git notes attaches supplementary annotations to existing commits without modifying the original commit object. Notes are stored separately under refs/notes/ and displayed alongside commits in git log. This is useful for adding post-hoc information — bug tracker references, review comments, audit metadata — that was not available when the commit was originally authored. The original commit hash remains unchanged.

Typical use cases

• Adding bug-tracker IDs or ticket numbers to commits after the fact, without rewriting history.
• Attaching code review comments or approval metadata to commits that have already been pushed.
• Enriching CI/CD pipeline results (build status, test coverage, deployment targets) as notes on specific commits.
• Maintaining team-specific annotations that should travel with commits but not alter their immutable content.

Diagram view

Inputs

Target commitNote textNotes ref namespace

→git notes

Results

New note objectOriginal commit unchangedNotes ref updated

Notes do not rewrite commits. They create a parallel metadata layer that references existing commits by hash.

Common mistakes

Mistake 1: assuming everyone sees notes automatically

Without pushing/fetching notes refs, collaborators may not see them.

Mistake 2: using notes as a replacement for commit messages

Commit messages remain the primary narrative; notes are supplemental.

Mistake 3: no governance for note content

Unstructured notes quickly become noisy and hard to trust.

Good follow-up reads

1. commit message conventions
2. release checklist discipline
3. git-show

• Adding a note to a commit that already has a note in the same namespace causes a conflict. Use git notes append to add to an existing note, or git notes edit to modify it.
• Notes are stored under a specific ref namespace (refs/notes/commits by default). You can create multiple namespaces with --ref=<name> for different types of annotations.
• Notes are not pushed or fetched by default. To share notes with a team, configure notes.ref or use git push origin refs/notes/*.
• Because notes don't change commit hashes, they are safe to add to shared/published commits — no history rewrite is involved.
• git log --show-notes displays notes inline with commit messages. Without this flag, notes are hidden from normal log output.
• Removing notes requires git notes remove or direct manipulation of the notes ref. Accidentally deleting notes is recoverable via reflog.

Try it yourself

1. Practice the git-notes command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Further reading

Keep going on the same topic:

• git mv
• git-prune Tutorial
• git pull Tutorial