git-notes

List all notes and the objects they are attached to

$ git notes list

$ git notes list [[object]]

$ git notes show [[object]]

$ git notes append [object]

$ git notes append --message="[message_text]"

$ git notes edit [[object]]

$ git notes copy [source_object] [target_object]

$ git notes remove [object]

git notes [--ref ref] subcommand [options] [object...]

--ref ref
    Specify the notes reference to operate on. This overrides the default notes ref configured via `notes.displayRef` or `notes.rewriteRef`. For example, `refs/notes/review`.

add
    Add a note to a given object. If no object is specified, it defaults to the current HEAD commit. Allows options for message source (file, stdin, message string) and behavior (overwrite, reuse).

show
    Show the notes for a given object. If no object is specified, it shows notes for HEAD.

list
    List all notes or notes for a specific object, displaying the object SHA-1 and the note SHA-1.

remove
    Remove notes for a given object or objects. Can take multiple objects as arguments or read from standard input.

copy from-object to-object
    Copy notes from one object to another. Useful for propagating notes when objects are rewritten.

append
    Append to the existing note for a given object. If no note exists, it creates one.

prune
    Remove notes that point to non-existent or unreachable objects, cleaning up the notes reference.

get-ref
    Print the currently active notes reference (e.g., `refs/notes/commits`).

merge
    Merge notes from another branch or repository into the current notes ref. Supports various merge strategies (e.g., `union`, `ours`, `theirs`).

rewrite
    Rewrite notes for objects that have been modified or rebased. This subcommand helps adjust notes to new object IDs after history rewriting operations.

pull
    Fetch notes from a remote repository and merge them into the local notes ref.

push
    Update notes on a remote repository from the local notes ref.

The git-notes command allows users to attach arbitrary information, or 'notes', to any Git object, most commonly commits, without modifying the object's original SHA-1 hash. This mechanism provides a flexible way to add metadata, comments, or annotations that are separate from the immutable commit history. Notes are stored in special Git references, typically within the `refs/notes/` namespace (e.g., `refs/notes/commits`).

Because notes are themselves Git objects (blobs for content, commits for history), they can be pushed, pulled, and merged like other Git references. Unlike commit messages, notes are designed to be mutable and can be updated, copied, or removed without rewriting history, offering a dynamic layer of annotation. Common use cases include adding code review comments, bug tracking IDs, build information, or any arbitrary metadata that should not be embedded into the permanent commit record. Its decentralized nature allows different individuals or teams to maintain their own sets of notes, which can then be shared and merged.

Notes are stored in separate Git references (`refs/notes/*`) and are not part of the main commit object history. Consequently, they are not automatically pushed or pulled unless explicitly configured or specified during remote operations. Merging notes from different sources can lead to conflicts, similar to code merges, requiring manual resolution based on configured merge strategies. While notes offer flexibility for local annotations, relying on them for critical, globally shared metadata might be less robust than embedding information directly into commit messages or using tags, as notes can be easily pruned or modified independently. Additionally, notes are not cryptographically signed or verified in the same way commits are, meaning their authenticity isn't guaranteed by default.

Notes are stored in a special hierarchy of references, typically under `refs/notes/`. By default, git-notes operates on `refs/notes/commits`. This default behavior can be customized via Git configuration options like `notes.displayRef` (for showing notes in `git log`) and `notes.rewriteRef` (for `git filter-branch` or `git rebase`). Different note namespaces can be created and used for distinct purposes, such as `refs/notes/review` for code review comments or `refs/notes/bugs` for bug tracking IDs, allowing for organizational flexibility.

Notes can be seamlessly displayed alongside commit information when viewing repository history. The `git log` command supports the `--show-notes` option to include notes in its output. Additionally, configuring `notes.displayRef` in your Git configuration ensures that notes from a specified ref are automatically displayed when running `git log` without needing explicit options, making annotations readily visible during history review.

The git-notes functionality was introduced in Git around version 1.6.0 (late 2008). Its primary motivation was to provide a flexible and non-destructive way to attach mutable metadata to immutable Git objects (like commits) without altering their SHA-1 checksums. This was a significant advancement over previous methods, which either required rewriting history (e.g., via `git filter-branch`) or embedding transient data directly into commit messages. Over time, its capabilities expanded with subcommands like `merge`, `pull`, and `push`, facilitating collaborative usage and management of notes across distributed repositories. Although not as widely adopted as commit messages or tags, git-notes remains a powerful tool for specific annotation and metadata management use cases, especially where altering the original commit history is undesirable.

git-commit(1), git-log(1), git-config(1), git-tag(1), git-push(1), git-pull(1), git-merge(1)