git notes para coding agents: texto al lado, el SHA no cambia

git notes añade, quita o lee texto pegado a un objeto sin tocarlo. El man (git-notes(1); git-scm.com/docs/git-notes HTTP 200, last-modified 2026-08-31; pie del man local Git 2.50.1.428.g0e8243, 2025-07-22; binario Git 2.50.1 / Apple Git-155): Add or inspect object notes. SYNOPSIS: list / add / copy / append / edit / show / merge / remove / prune / get-ref.

No es el mensaje del commit. El commit queda con el mismo SHA. El man: without touching the objects themselves. Tampoco es un tag: el tag es un ref; la nota vive en refs/notes/commits (default) y apunta al objeto.

Contrato: git notes add -m <msg>. show. Cero editor. Cero -f autónomo. Cero merge. Cero edit.

Qué hace (y qué no)

El man: A typical use of notes is to supplement a commit message without changing the commit itself. log las imprime indentadas tras una línea Notes:. --no-notes las oculta.

notes.rewriteRef no está set por defecto. Aunque notes.rewrite.amend / notes.rewrite.rebase existan, sin esa ref no se copian. Un commit --amend o un rebase deja la nota en el SHA viejo.

clone no trae refs/notes/*. Hay que pedirlas (fetch origin refs/notes/commits:refs/notes/commits). format-patch --notes las pone como comentario después de ---.

Verificado 2026-09-06 (Git 2.50.1 / Apple Git-155). Repo con un commit:

• git notes / git notes list (vacío): 0.
• git notes show: 1, no note found for object.
• git notes add sin -m/-F: 128, Terminal is dumb, but EDITOR unset / please supply the note contents using either -m or -F option.
• git notes add -m 'review: ok': 0. rev-parse HEAD igual que antes.
• git notes add -m 'dup': 1, Cannot add notes. Found existing notes… Use '-f'.
• git notes add -f -m 'overwrite': 0, Overwriting existing notes.
• git notes show: el texto. list: <note-object> <annotated-object>.
• git notes get-ref: refs/notes/commits.
• git notes remove HEAD: 0. Otra vez: 1, Object HEAD has no note. --ignore-missing: 0.
• git notes foo: 129, unknown subcommand.
• Fuera de un repo: 128, not a git repository.
• git notes merge: 129, must specify a notes ref to merge.
• git notes edit sin editor: 128.
• Nota en blob y tree: 0. El man no limita a commits.
• commit --amend: la nota sigue en el SHA viejo. show del HEAD nuevo: 1.
• git rebase de un commit con nota: la nota queda en el SHA pre-rebase.
• git clone: 0 en notes list, cero refs/notes/*.
• git format-patch -1 --stdout --notes: bloque Notes: después de ---.
• --ref=review add -m '…': 0. get-ref con --ref=review = refs/notes/review.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
Anotar HEAD	git notes add -m '…'	commit --amend “para el mismo efecto”
Leer	git notes show / log -1	show del commit (el mensaje, no la nota)
¿Hay nota?	git notes list <SHA>	cat .git/notes
Ref actual	git notes get-ref	adivinar refs/notes/commits
Quitar	git notes remove --ignore-missing HEAD	remove a ciegas (exit 1 si no hay)

Prohibido en autónomo:

• Editor (add/edit/append sin -m/-F). Verificado: 128.
• -f. Pisa la nota. El man: Abort if the object already has notes (use -f to overwrite).
• merge / merge --commit / merge --abort. Worktree .git/NOTES_MERGE_WORKTREE. Verificado: merge sin args 129.
• copy -f. Pisa el destino.
• prune sin -n. El man: Remove all notes for non-existing/unreachable objects. Primero -n.
• Tratar la nota como parte del commit. show del commit no imprime notes. amend/rebase no las mueven sin notes.rewriteRef.
• Esperar notes tras clone. Verificado: la ref no viaja.
• Volcar notes list entero al contexto. El default lista todas.

Receta (60 segundos)

Solo si un humano pidió anotar un SHA sin reescribirlo (review local, CI id, “por qué este cherry”). Si el ticket es “cambiar el mensaje”: commit (y eso sí cambia el SHA). Si es “otra sesión”: worktree.

git status -sb
git notes get-ref
git notes add -m '<texto corto>' HEAD
git notes show HEAD

• 0 + el texto: reporta el SHA (sigue igual) y para. No hagas -f. No commitees refs/notes/ a main a menos que el ticket lo pida.
• Ya había nota: 1. Para. No -f.
• Otro: error. No abras editor. No merge.

Cierre = show + SHA intacto. Cero push a main. Cero edit.

notes vs commit vs tag

commit crea un objeto. La nota no. tag nombra un commit en refs/tags/. La nota vive en refs/notes/commits y el objeto anotado puede ser commit, tree o blob.

log las muestra si la config de display lo permite. format-patch --notes las exporta como comentario, no como parte del commit.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. Notes no son sandbox ni changelog: son un blob al lado del objeto.