git-notes

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Notes

## Overview

Git notes attach metadata to commits (or any Git object) without modifying the objects themselves. Notes are stored separately and displayed alongside commit messages.

**Core principle:** Add information to commits after creation without rewriting history.

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Notes ref** | Storage location, default `refs/notes/commits` |
| **Non-invasive** | Notes never modify SHA of original object |
| **Namespaces** | Use `--ref` for different note categories |
| **Display** | Notes appear in `git log` and `git show` output |

## Quick Reference

| Task | Command |
|------|---------|
| Add note | `git notes add -m "message" <sha>` |
| View note | `git notes show <sha>` |
| Append | `git notes append -m "message" <sha>` |
| Edit | `git notes edit <sha>` |
| Remove | `git notes remove <sha>` |
| Use namespace | `git notes --ref=<name> <command>` |
| Push notes | `git push origin refs/notes/<name>` |
| Fetch notes | `git fetch origin refs/notes/<name>:refs/notes/<name>` |
| Show in log | `git log --notes=<name>` |

For complete command reference, see `references/commands.md`.

## Essential Patterns

### Code Review Tracking

```bash
# Mark reviewed
git notes --ref=reviews add -m "Reviewed-by: Alice <alice@example.com>" abc1234

# View review status
git log --notes=reviews --oneline
```

### Sharing Notes

```bash
# Push to remote
git push origin refs/notes/reviews

# Fetch from remote
git fetch origin refs/notes/reviews:refs/notes/reviews
```

### Preserving Through Rebase

```bash
git config notes.rewrite.rebase true
git config notes.rewriteMode concatenate
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Notes not showing in log | Specify ref: `git log --notes=reviews` or configure `notes.displayRef` |
| Notes lost after rebase | Enable: `git config notes.rewrite.rebase true` |
| Notes not on remote | Push explicitly: `git push origin refs/notes/commits` |
| "Note already exists" error | Use `-f` to overwrite or `append` to add |

## Best Practices

| Practice | Rationale |
|----------|-----------|
| Use namespaces | Separate notes by purpose (reviews, testing, audit) |
| Be explicit about refs | Always specify `--ref` for non-default notes |
| Push notes explicitly | Document sharing procedures in team guidelines |
| Use append over add -f | Preserve note history when accumulating |
| Configure rewrite preservation | Run `git config notes.rewrite.rebase true` before rebasing |

# Git Notes Command Reference

Complete reference for all git notes commands and options.

## Basic Operations

### Add a Note

```bash
# Add note to current HEAD
git notes add -m "Reviewed by Alice"

# Add note to specific commit
git notes add -m "Tested on Linux" abc1234

# Add note from file
git notes add -F review-comments.txt abc1234

# Add note interactively (opens editor)
git notes add abc1234

# Overwrite existing note
git notes add -f -m "Updated review status" abc1234

# Add empty note
git notes add --allow-empty abc1234
```

### View Notes

```bash
# Show note for HEAD
git notes show

# Show note for specific commit
git notes show abc1234

# View commit with notes in log

From NeoLabHQ/context-engineering-kit, GPL-3.0.

More from NeoLabHQ/context-engineering-kit