notes_skill

Overview

This skill teaches how to use Git Notes to attach metadata to commits and other Git objects without rewriting history. It provides practical commands, namespaces, and patterns for tracking reviews, test results, audit annotations, and shared notes across remotes. Use it to supplement commit messages non-invasively and preserve structured metadata during rebases and merges.

How this skill works

The skill explains git notes commands (add, append, show, edit, remove, copy, merge, prune) and how notes are stored under refs/notes/* so original object SHAs remain unchanged. It covers multi-namespace workflows, pushing/fetching notes to remotes, and configuring note preservation during rebase/amend. Included patterns show how to attach review status, test outputs, and audit records while surfacing them in git log and git show.

When to use it

• Add review or approval metadata after commits without changing history
• Record CI/test outcomes or platform-specific results tied to commits
• Attach security or audit annotations that must be preserved separately
• Share non-invasive metadata with team via refs/notes pushed to remote
• Preserve contextual comments across rebases or cherry-picks

Best practices

• Use namespaces (refs/notes/<name>) to separate reviews, testing, and audits
• Always specify --ref when using non-default notes to avoid confusion
• Prefer git notes append over add -f to preserve note history
• Push and fetch notes explicitly (refs/notes/<name>) to share with teammates
• Enable notes.rewrite.rebase and notes.rewrite.amend before rebasing or amending to preserve notes

Example use cases

• Code review tracking: mark reviewed, append comments, and show review status in git log --notes=reviews
• Test annotation: attach CI pass/fail, coverage, and links to build results under refs/notes/testing
• Audit trail: record security review details and searchable audit messages in refs/notes/audit
• Sharing: push refs/notes/reviews and fetch on collaborators to keep review metadata synchronized
• Bulk ops: script adding or removing notes for ranges of commits by piping commit SHAs