git cat-file para coding agents: tipo y talla, no el blob al LLM

git cat-file no es show. El man (git-cat-file(1), Git 2.50.1 / Apple Git-155; git-scm.com/docs/git-cat-file HTTP 200, last-modified 2026-08-31; pie del man local Git 2.50.1.428.g0e8243, 2025-07-22) imprime contenido o propiedades de un objeto: tipo, talla, existencia, pretty-print. HEAD, index y working tree no se mueven. El synopsis pide un modo: <type> <object>, o (-e | -p | -t | -s) <object>, o --textconv / --filters, o la familia --batch.

Sin argumentos: usage, 129. -t y -s juntos: options '-s' and '-t' cannot be used together, 129. Eso no es rev-parse (resolver el nombre) ni ls-files (index + working tree). El contrato: preguntar tipo o talla, no volcar el blob al LLM.

GitHub Docs (REST API endpoints for Git blobs, HTTP 200 2026-09-04): Get a blob pide Contents read y devuelve el contenido en el remoto. No sustituye el clone ni autoriza pegar el payload al prompt.

Tres letras, un objeto

Pregunta	Comando	Qué imprime
¿Qué tipo es?	git cat-file -t HEAD	commit / tree / blob / tag
¿Cuántos bytes?	git cat-file -s HEAD:path	entero; blob hello\n → 6
¿Existe?	git cat-file -e <object>	nada; exit 0 / 1 / 128
Pretty-print	git cat-file -p HEAD	commit/tree/tag legible
Raw de un tipo	git cat-file blob <sha>	bytes del blob

Verificado 2026-09-04 (Git 2.50.1 / Apple Git-155):

• -t HEAD → commit. -t del blob → blob. -t del tree → tree. Tag anotado → tag.
• -s del blob hello\n → 6. -s HEAD → talla del objeto commit, no del tree.
• -e de un objeto válido: 0, stdout y stderr vacíos.
• -e de 40 hex que no existen: 1, sin mensaje.
• -e abc (malformado): Not a valid object name, 128.
• -t nope: Not a valid object name, 128.
• git cat-file tree HEAD (commit pedido como tree): 0 — el man permite dereferenciar trivial (tree desde commit, blob desde tag).
• git cat-file tree <blob> / git cat-file blob HEAD: bad file, 128.
• -p del blob imprime el contenido. -p del tree lista mode type sha TAB path (un nivel del objeto tree, no el disco).

El man (CAVEATS): la talla en disco no te dice qué ref “pesa”. Un packed no-delta puede ser más grande que los que deltan contra él; cuál es base es arbitrario y cambia en un repack. Varias copias: indefinido cuál se reporta.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
Tipo de HEAD	git cat-file -t HEAD	git show HEAD al LLM
¿Este SHA es blob?	git cat-file -t -- <sha>	abrir el file en disco
¿Existe el objeto?	git cat-file -e <sha>	parsear fatal de -p
Talla antes de leer	git cat-file -s HEAD:path	wc del working tree
Info de varios SHA	git cat-file --batch-check + stdin	--batch-all-objects

Prohibido en autónomo:

• Volcar -p / blob / --batch de un file al LLM. El man: <type> devuelve el contenido raw (descomprimido). Un agente one-shot pregunta -t y -s; si el blob es grande, no lo imprime.
• Mezclar -t y -s. Verificado: 129. Un flag por invocación.
• --batch-all-objects sin (ni con) un pathspec humano. El man: recorre todos los objetos del store y de los alternates, no solo los alcanzables; ignora git-replace. Verificado: sin --batch / --batch-check → requires a batch mode, 129. Con --batch-check lista commit + tree + blob de un repo mínimo. En un clone real eso es el object database entero.
• --textconv / --filters sin rev:path. Verificado: <object>:<path> required, 128. --filters corre smudge y conversión EOL del working tree; no es “el blob crudo”.
• --follow-symlinks fuera de --batch / --batch-check. El man: no funciona (hoy) con :link del índice; un symlink que apunta fuera del tree imprime symlink N + el path (/etc/passwd en el ejemplo del man). Un agente no sigue links a ciegas.
• -z (input NUL, output newline). El man: deprecated; la salida puede ser ambigua. Usa -Z (NUL en ambos lados) si parseas.
• Tratar --batch-check “missing” como fatal. Verificado: printf 'nope\n' | git cat-file --batch-check imprime nope missing y sale 0. El 128 es para nombres malformados en modo no-batch.
• Encadenar cat-file blob a un commit o a un file nuevo. Leer el objeto no es permiso de escribir.

--batch-command: stdin con contents <object>, info <object>, flush. Verificado: comando desconocido → unknown command, 128. Un agente no abre esa REPL.

Receta (60 segundos)

Solo en un worktree propio:

git status -sb
git cat-file -t HEAD
git cat-file -s HEAD:README.md
git cat-file -e HEAD:README.md; echo $?

Si el ticket pide “¿estos SHA existen?”:

printf '%s\n' "$SHA1" "$SHA2" | git cat-file --batch-check

Default --batch-check: %(objectname) %(objecttype) %(objectsize). Parseable. --batch añade el contenido crudo debajo: no lo uses en autónomo.

-e es el gate de existencia. 0 = objeto válido. 1 = 40 hex bien formado que no está. 128 = nombre inválido. No tragues el 1 como “ok”.

El <type> del primer synopsis (man): suele coincidir con el tipo real, pero permite dereference trivial. Pedir tree de un commit funciona; pedir blob de un commit no. Verificado: bad file, 128.

Batch vs un objeto

El man parte en dos modos. Sin --batch*: un objeto en argv. Con --batch / --batch-check / --batch-command: stdin. -Z: NUL en input y output (recomendado para scripts). --buffer: no flushes por objeto; más rápido en lote, peor para un REPL.

--use-mailmap con -s / batch: la talla reportada es la del objeto como si las identidades ya estuvieran canónicas. No cambia el SHA.

GitHub Get a blob: el JSON del remoto no es cat-file -p. Un agente que quiere el blob de este clone corre cat-file; el que quiere el blob de github.com usa la API con Contents read, no inventa 40 hex.

Checklist

• Worktree propio. git status -sb. Un modo por invocación.
• Default de inspección: -t, luego -s, luego -e. Cero dump de blob.
• -e: 0 existe, 1 missing, 128 malformado.
• Cero -t+-s, cero --batch-all-objects, cero --filters sin path.
• Cero -z; -Z si parseas lote.
• Pretty-print humano es show. Resolver el nombre es rev-parse. Listar index/disco es ls-files.

FAQ

¿cat-file -p HEAD es lo mismo que git show? No. show pretty-printa y (en un commit) puede incluir diff. cat-file -p del commit imprime tree/author/committer/mensaje, sin parche. El man de cat-file no habla de diff.

¿Por qué -e a veces es 1 y a veces 128? El man: formato inválido → no-cero con error en stderr. Verificado: hex de 40 que no está → 1 silencioso; abc → 128 con Not a valid object name.

¿Puedo pedir blob de un tag anotado? El man lo permite si el tag apunta a un blob (dereference trivial). Un tag anotado que apunta a un commit no es un blob: bad file, 128. Primero -t.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. cat-file no es show: inspecciona el objeto; no arma un parche.