notes Git Command Guide

The git notes command adds, removes, or reads notes attached to objects, without touching the objects themselves. By default, notes are saved to and read from refs/notes/commits, but this default can be overridden for different note namespaces.

git notes Syntax:

git notes [list [<object>]]
git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes edit [--allow-empty] [<object>] [--[no-]stripspace]
git notes show [<object>]
git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
git notes merge --commit [-v | -q]
git notes merge --abort [-v | -q]
git notes remove [--ignore-missing] [--stdin] [<object>...]
git notes prune [-n] [-v]
git notes get-ref

Note Management Commands:

Command	Description
list [<object>]	List notes for object or all notes
add	Add note to object
copy	Copy note from one object to another
append	Append to existing note
edit	Edit existing note
show	Display note for object
merge	Merge notes from different refs
remove	Remove note from object
prune	Remove notes for non-existent objects
get-ref	Show current notes ref

Note Content Options:

Option	Description
-f, --force	Overwrite existing notes
--allow-empty	Allow empty notes
--separator=<break>	Specify paragraph break
--no-separator	Don’t add separator
--stripspace	Strip whitespace from note
--no-stripspace	Preserve whitespace
-F <file>	Read note from file
-m <msg>	Specify note message
-c <object>	Reuse note from object
-C <object>	Reuse and edit note from object
-e, --edit	Edit note in editor

Note Reference Options:

Option	Description
<object>	Object to attach note to
<notes-ref>	Notes reference to merge
-s <strategy>	Merge strategy (manual, ours, theirs, union, cat_sort_uniq)

Basic Note Operations:

Add Notes to Commits:

# Add note to specific commit
git notes add -m "Reviewed by QA team" HEAD

# Add note from file
echo "Security review completed" | git notes add -F - HEAD~1

# Add note with editor
git notes add HEAD~2

View and List Notes:

# Show note for specific commit
git notes show HEAD

# List all notes
git notes list

# Show notes for specific commit
git notes show abc123

# List notes with commit info
git notes list | xargs -I {} sh -c 'echo "Note for {}:"; git notes show {}; echo'

Edit Existing Notes:

# Edit note in editor
git notes edit HEAD

# Append to existing note
git notes append -m "Additional review comments" HEAD

# Replace note content
git notes add -f -m "Updated review status" HEAD

Advanced Note Management:

Multiple Note Namespaces:

# Use custom notes ref
git notes --ref=reviews add -m "Code review approved" HEAD

# List notes from specific ref
git notes --ref=reviews list

# Show notes from custom ref
git notes --ref=reviews show HEAD

Note Copying and Merging:

# Copy note from one commit to another
git notes copy HEAD~1 HEAD

# Copy note via stdin
echo "abc123" | git notes copy HEAD~1

# Merge notes from different refs
git notes merge reviews
git notes merge --commit reviews

Note Removal and Cleanup:

# Remove note from commit
git notes remove HEAD

# Remove multiple notes
git notes remove HEAD~1 HEAD~2 HEAD~3

# Remove notes for non-existent commits
git notes prune

# Dry-run prune operation
git notes prune -n

Integration with Git Workflows:

Code Review Integration:

# Add review notes during code review
git notes add -m "Approved for merge" HEAD

# Add reviewer information
git notes append -m "Reviewed-by: $(git config user.name) <$(git config user.email)>"

# Mark as reviewed
git notes add -m "Status: approved" HEAD

Release Notes Management:

# Add release notes to commits
git notes add -m "Release: v2.1.0 - Added new features" HEAD

# Track deployment information
git notes append -m "Deployed: $(date) to production"

# Add changelog entries
git notes add -m "Changelog: Fixed critical security issue" HEAD

Quality Assurance Tracking:

# Track testing status
git notes add -m "QA: Passed all tests" HEAD

# Add test coverage information
git notes append -m "Coverage: 95% - meets requirements"

# Track security review
git notes add -m "Security: Approved by security team" HEAD

Note Formatting and Display:

Custom Note Display:

# Show notes in log output
git log --notes

# Show notes from specific ref
git log --notes=reviews

# Show all notes
git log --notes=*

# Format notes in log
git log --format="%H %s%nNotes:%n%N"

Note Content Formatting:

# Configure note formatting
git config notes.displayRef "*"

# Configure note separator
git config notes.rewriteMode overwrite

# Configure note editor
git config notes.editor vim

Note Merging Strategies:

Merge Strategy Options:

# Manual merge strategy
git notes merge -s manual reviews

# Use ours strategy (keep current)
git notes merge -s ours reviews

# Use theirs strategy (overwrite with incoming)
git notes merge -s theirs reviews

# Concatenate notes
git notes merge -s cat_sort_uniq reviews

# Union strategy
git notes merge -s union reviews

Conflict Resolution:

# Abort merge on conflicts
git notes merge --abort

# Commit after manual resolution
git notes merge --commit

# Verbose merge output
git notes merge -v reviews

Integration with External Tools:

Issue Tracker Integration:

#!/bin/bash
# Add issue references as notes
commit_msg=$(git show --no-patch --format=%B HEAD)

# Extract issue numbers
issue_ids=$(echo "$commit_msg" | grep -o "#[0-9]\+" | tr '\n' ' ')

if [ -n "$issue_ids" ]; then
    git notes add -m "Related issues: $issue_ids" HEAD
fi

Documentation Enhancement:

# Add documentation links to commits
git notes add -m "Documentation: https://docs.company.com/feature-xyz" HEAD

# Add API references
git notes append -m "API: /api/v2/endpoints"

# Add architectural decisions
git notes add -m "ADR: Decision to use microservices architecture" HEAD

Performance and Maintenance:

Large Repository Handling:

# Prune notes for deleted commits
git notes prune -v

# Check notes integrity
git notes list | wc -l && echo "notes in repository"

# Clean up old notes
git notes prune --dry-run | head -10

Note Backup and Migration:

# Export notes for backup
git notes list | while read hash; do
    echo "=== $hash ==="
    git notes show "$hash"
done > notes-backup.txt

# Import notes from backup
while read hash; do
    read note
    git notes add -m "$note" "$hash"
done < notes-backup.txt

Troubleshooting Common Issues:

Note Not Appearing:

# Check if notes exist
git notes list | grep "$(git rev-parse HEAD)"

# Check notes ref
git notes get-ref

# Verify note content
git cat-file -p "$(git notes get-ref)":HEAD

Merge Conflicts:

# Handle note merge conflicts
git notes merge -s manual reviews

# Edit conflicting note
git notes edit HEAD

# Complete merge
git notes merge --commit

Permission Issues:

# Check notes ref permissions
ls -la .git/refs/notes/

# Fix permissions if needed
chmod 644 .git/refs/notes/commits

Encoding Problems:

# Handle special characters in notes
git notes add -m "Note with special chars: äöü" HEAD

# Configure encoding
git config i18n.commitEncoding UTF-8

Caution

Notes modify repository metadata but not commit objects themselves. Note operations are separate from commit history. Use appropriate refs for different note purposes.

Real-World Usage Examples:

Code Review Workflow:

#!/bin/bash
# Enhanced code review with notes

# Add review status
git notes add -m "Review-Status: approved" HEAD

# Add reviewer information
git notes append -m "Reviewed-by: $(git config user.name)"
git notes append -m "Review-Date: $(date)"

# Add review comments
git notes append -m "Comments: Excellent implementation of feature"

# Mark for merge
git notes add -m "Ready-for-Merge: yes" HEAD

# Generate review summary
echo "=== Review Summary ==="
git log --oneline --notes=reviews -1

Release Management:

# Track release information
git notes add -m "Release: v3.2.1" HEAD
git notes append -m "Release-Date: $(date)"
git notes append -m "Release-Notes: Bug fixes and performance improvements"

# Add deployment tracking
git notes append -m "Deployed: $(date) to staging"
git notes append -m "Deployed: $(date) to production"

# Track rollback information
git notes add -m "Rollback: Reverted due to critical bug" HEAD

Compliance and Auditing:

# Add compliance information
git notes add -m "Compliance: SOX compliant" HEAD
git notes append -m "Audited-by: compliance-team@company.com"
git notes append -m "Audit-Date: $(date)"

# Add security review notes
git notes add -m "Security-Review: passed" HEAD
git notes append -m "Security-Reviewer: security-team@company.com"

# Track change approval
git notes append -m "Approved-by: change-advisory-board"

Tip

Use separate note refs for different purposes (reviews, releases, compliance). Combine with git log —notes for enhanced commit display. Notes don’t affect commit hashes.

How do notes differ from commit messages?

Notes are separate metadata attached to commits, while commit messages are part of the commit object itself. Notes can be added/removed without changing commit hashes.

Can notes be attached to objects other than commits?

Yes, notes can be attached to any Git object (commits, trees, blobs, tags). Most common use case is commit notes for additional metadata.

What’s the difference between git notes and git tags?

Tags mark specific commits with names, notes attach additional information to any object. Tags are references, notes are separate objects with references.

How do notes work with git log?

Use git log —notes to display notes in log output. Configure notes.displayRef to control which note refs are shown by default.

Can notes be merged between repositories?

Yes, use git notes merge to combine notes from different repositories or note refs. Supports various merge strategies for conflict resolution.

What’s the performance impact of notes?

Notes add minimal overhead - separate objects with references. Large numbers of notes may require occasional pruning of orphaned notes.

How do notes interact with git rebase?

Rebase preserves notes by default. Use —no-notes with rebase if you want to exclude notes from rebased commits.

Can notes contain binary data?

Yes, notes can contain any content. Use -F option to read from files for binary or large text content.

How do I backup and restore notes?

Use git notes list to enumerate notes, git notes show to extract content. Restore by recreating notes on target repository.

What’s the relationship between notes and git describe?

git describe uses tags for naming; notes provide additional metadata. Can combine both for comprehensive commit annotation.

Can notes be used for workflow automation?

Yes, scripts can parse notes for automation triggers. Use git notes show in scripts to extract metadata for conditional processing.

How do notes work with Git LFS or large files?

Notes work normally with any Git repository. Can annotate commits containing LFS files or any other Git objects.

What’s the difference between notes and git attributes?

Git attributes control Git behavior for files; notes provide metadata about objects. Different purposes - attributes affect Git operations, notes provide information.

Can notes be used for code review workflows?

Yes, perfect for review workflows. Add review status, reviewer information, approval status, and comments as notes on commits.

How do notes interact with git bisect?

Bisect operates on commit objects, notes are separate. Bisect doesn’t consider note content when finding commits meeting criteria.

Can notes be used for compliance tracking?

Excellent for compliance - add audit information, approval status, compliance checks, and regulatory metadata as notes on relevant commits.

What’s the storage overhead of notes?

Notes are separate objects, so they add to repository size. Each note is a blob object plus reference. Minimal overhead for typical usage.

How do notes work with git worktrees?

Notes work normally with worktrees. Note refs are shared across worktrees, note content available in all worktrees.

Can notes be used for documentation purposes?

Yes, attach documentation links, API references, architectural decisions, and other documentation metadata to relevant commits.

How do I handle note conflicts in collaborative workflows?

Use git notes merge with appropriate strategies. Manual resolution for complex conflicts, automated strategies for simple cases.

Applications of the git notes command

1. Code Review Enhancement: Attach review status, comments, and approval information to commits
2. Release Management: Track release information, deployment status, and version metadata
3. Compliance Auditing: Add regulatory compliance information and audit trails to commits
4. Documentation Linking: Attach documentation references and architectural decisions to code changes
5. Workflow Automation: Use notes as triggers for automated processes and integrations
6. Collaborative Annotation: Enable team members to add contextual information to commits