App Development & Staff Augmentation Company India, USA

Git Notes

Git notes let you attach extra text to any commit — or other Git object — without modifying the object itself. Because the commit hash is not changed, notes are safe to use on published history. The annotation lives alongside the commit as a separate object, linked through a special ref. This makes notes ideal for post-hoc information: code review decisions, CI build results, deployment records, or security audit findings recorded after the fact.

How Notes Work Internally

Notes are stored under refs/notes/commits by default. Each note is a blob object whose content is your annotation text. A special tree maps commit hashes to their note blobs. The commit you annotate is completely untouched — its SHA stays the same. This means notes never break existing clones, tags, or CI references.

Notes storage model

Text

Normal commit object (completely unchanged):
  SHA: a3f1c2d...
  tree: ...
  parent: ...
  message: "Add authentication module"

Notes ref (refs/notes/commits):
  └── tree:
        └── a3f1c2d... → blob: "Reviewed by Alice on 2024-05-01. Approved for production."

Adding a Note to a Commit

Add a note to the most recent commit

Bash

git notes add -m "Reviewed by Alice — approved for production" HEAD

Add a note to a specific commit hash

Bash

git notes add -m "Security audit: no vulnerabilities found" a3f1c2d

Add a multi-line structured note

Bash

git notes add -m "CI Results:
  - Unit tests:        PASS (342/342)
  - Integration tests: PASS (87/87)
  - Coverage:          94.3%
  - Build duration:    2m 14s
  - Deployed to:       staging-v2.example.com" HEAD

Open your editor to write a longer note

Bash

# Opens $EDITOR for composing the note
git notes add HEAD

Showing Notes

Show the note for a specific commit

Bash

git notes show HEAD

# Or for a specific hash
git notes show a3f1c2d

Show notes inline in git log output

Bash

git log --show-notes

# Show notes for the last 5 commits
git log -5 --show-notes

git log --show-notes output

Text

commit a3f1c2d83e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b
Author: Jane Developer <jane@example.com>
Date:   Mon May 20 14:23:11 2024 +0000

    Add authentication module

Notes:
    Reviewed by Alice — approved for production

Editing a Note

Edit an existing note

Bash

# Open the existing note in your editor
git notes edit HEAD

# Overwrite a note inline with -f (force)
git notes add -f -m "Updated review: approved with minor nits fixed" HEAD

Note

git notes add will fail if a note already exists for that commit. Use -f to force overwrite it inline, or git notes edit to open the current note in your editor where you can modify it.

Appending to a Note

If a note already exists and you want to add more information without replacing it, use git notes append. The new text is added after the existing content.

Append text to an existing note

Bash

git notes append -m "Follow-up: dependency patched to fix CVE-2024-1234" HEAD

# View the full combined note
git notes show HEAD

Note after appending

Text

Reviewed by Alice — approved for production
Follow-up: dependency patched to fix CVE-2024-1234

Removing a Note

Remove a note from a commit

Bash

git notes remove HEAD

# Remove from a specific commit hash
git notes remove a3f1c2d

Notes Namespaces

By default all notes go into refs/notes/commits. You can maintain separate namespaces for different types of annotations — for example one namespace for code reviews and another for CI results. This keeps different annotation types independent and allows selective sharing of only the namespaces your team needs.

Notes with custom namespaces

Bash

# Add a note in the code-review namespace
git notes --ref=refs/notes/code-review add -m "Approved by Alice" HEAD

# Add a note in the ci namespace
git notes --ref=refs/notes/ci add -m "Build #4821: PASS, coverage 94%" HEAD

# Show notes from a specific namespace
git notes --ref=refs/notes/code-review show HEAD

# Show multiple namespaces in git log
git log --notes=refs/notes/code-review --notes=refs/notes/ci -5

Pushing Notes to a Remote

Git notes are stored in refs/notes/* and are NOT automatically pushed or fetched along with branches and tags. You must explicitly push them and configure fetch rules. This surprises many developers who add notes locally and expect teammates to see them.

Push notes to the remote

Bash

# Push the default notes ref
git push origin refs/notes/commits

# Push all notes namespaces at once
git push origin "refs/notes/*"

# Push a specific namespace
git push origin refs/notes/code-review

Configure automatic note fetching

Bash

# Add this to .git/config so that git fetch also retrieves notes
git config --add remote.origin.fetch "+refs/notes/*:refs/notes/*"

# Now a regular git fetch will also get notes
git fetch origin

.git/config after adding the fetch refspec

Text

[remote "origin"]
    url = git@github.com:org/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/notes/*:refs/notes/*          ← added

Warning

Git notes are NOT pushed or pulled by default. If you add notes locally without configuring the push and fetch refspecs shown above, your team members will never see them. Always document the fetch configuration in your team onboarding guide when using notes.

Listing All Noted Commits

List commits that have notes

Bash

git notes list
# Returns: blob-hash  commit-hash pairs
# 8f14e0b9...  a3f1c2d...
# 1a2b3c4d...  9e8f7a6b...

Copying Notes After Cherry-Pick

When you cherry-pick a commit, the new commit gets a different hash. Any notes attached to the original commit do not automatically follow. Use git notes copy to re-attach them.

Copy a note from original to cherry-picked commit

Bash

# After cherry-picking abc1234 to create def5678
git notes copy abc1234 def5678

Use Cases

Use Case	Example Note Content	Namespace
Code review records	Reviewed by Alice on 2024-05-01 — approved	refs/notes/code-review
CI/CD build results	Build #4821 PASS, coverage 94%, 2m 14s	refs/notes/ci
Security audits	Scanned by Snyk: no high-severity issues found	refs/notes/security
Deployment tracking	Deployed to prod at 2024-05-01 15:32 UTC by CI	refs/notes/deploy
Performance benchmarks	p99 latency 23ms (baseline was 41ms)	refs/notes/perf
Bug report links	Fixes JIRA-1234, regression confirmed in v2.1.0	refs/notes/issues

Tip

Automate CI notes with a post-build script: after every pipeline run, call git notes add -f -m 'CI: $STATUS at $TIMESTAMP' $COMMIT_SHA and push with git push origin refs/notes/ci. Then git log --notes=refs/notes/ci gives a searchable build history attached directly to your commits.