git fsck para coding agents: integridad, no housekeeping

git fsck verifica la conectividad y la validez de los objetos del clone local. El man (git-fsck(1); git-scm.com/docs/git-fsck HTTP 200, last-modified 2026-08-31; pie del man local Git 2.54.0, 2026-04-19; binario Git 2.50.1 / Apple Git-155): Verifies the connectivity and validity of the objects in the database. SYNOPSIS: git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] [--[no-]dangling] [--[no-]progress] [--connectivity-only] [--[no-]name-objects] [--[no-]references] y objetos opcionales.

No es gc. gc comprime, empaqueta y puede tirar inalcanzables con gracia. fsck no reescribe packs. No borra. No toca el working tree ni el índice.

Tampoco es git prune. prune es plumbing que sí borra sueltos inalcanzables. El man de prune: In most cases, users should run git gc, which calls git prune. Un agente no sustituye fsck por prune.

Contrato: git fsck. Cero --lost-found. Cero --no-reflogs. Cero --strict en un clone ajeno. Dangling no es fallo.

Qué hace (y qué no)

Sin argumentos, fsck usa el índice, todas las refs de refs/ y los reflogs como heads (salvo --no-reflogs). --full es default: también mira packs y alternates. --dangling es default: imprime objetos presentes que nadie usa directamente. --no-dangling calla esa línea. --references (default) corre git refs verify.

--unreachable lista lo que existe y no se alcanza desde esos heads. --connectivity-only no lee blobs: confirma que los blobs referenciados existen. Detecta corrupción en commits/trees; no en el contenido de un blob. --strict caza el bit g+w en modos viejos. El man: repos establecidos (kernel, Git, sparse) disparan ese check. Un agente no lo pone en un clone que no es suyo.

--lost-found escribe dangling a .git/lost-found/commit/ u other/. Si es blob, mete el contenido, no solo el SHA. Eso muta .git/. Fuera del contrato.

--no-reflogs deja de tratar el reflog como head: sirve para cazar commits que ya no están en una ref. Un agente no lo usa para “limpiar”. --name-objects añade un nombre tipo HEAD@{{n}} al SHA alcanzable. --verbose es chatty. --root / --tags reportan raíces y tags. Un argumento SHA que no está en la base: object missing y exit 1.

DISCUSSION del man: fsck imprime corrupción (missing / bad / hash mismatch). dangling no es corrupción. unreachable tampoco, salvo que hayas omitido un head. Un hash mismatch sí es integridad rota.

Verificado 2026-09-06 (Git 2.50.1 / Apple Git-155). Repo mínimo, un commit:

• git fsck: 0. Silencio. rev-parse HEAD igual. status -sb sin cambios en tracked.
• git fsck --no-dangling: 0.
• git fsck --connectivity-only: 0.
• git fsck --strict: 0 (repo nuevo).
• git fsck --unreachable: 0.
• git fsck --root: 0. Imprime root y el SHA del commit raíz. HEAD igual.
• git fsck --tags: 0.
• git fsck --verbose: 0. Chatty: refs, objects, reflog, connectivity.
• Blob suelto (hash-object -w, no en el índice): 0 y dangling blob + SHA. --no-dangling: silencio, 0.
• git fsck --lost-found: 0. Crea .git/lost-found/other/ más el SHA, con el contenido del blob.
• git fsck --foo: 129, unknown option `foo'.
• SHA inventado como argumento: 1, object missing.
• Fuera de un repo: 128, not a git repository.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
¿El object database está sano?	git fsck	tratar dangling blob como fallo
Menos ruido	git fsck --no-dangling	--lost-found “por si acaso”
¿Existe este SHA?	git cat-file -e más el SHA	fsck con un SHA inventado y alarmar el 1
Housekeeping	gc --auto	git prune / --no-reflogs

Prohibido en autónomo:

• --lost-found. Escribe blobs en .git/lost-found/. Mutación. No es diagnóstico.
• --no-reflogs para “encontrar basura”. El default incluye reflogs como heads a propósito.
• --strict en un clone que no acabas de crear. El man: proyectos viejos disparan el check.
• --verbose volcado al LLM. Chatty. Cierre = exit code + si hubo missing / hash mismatch.
• Tratar dangling / unreachable como corrupción. Default 0. Reporta y para.
• Confundirlo con gc. gc empaqueta. fsck no.
• git prune / git repack porque fsck listó dangling. Eso es housekeeping, no fsck.
• Correr fsck en el worktree del humano o en main. Solo worktree propio.
• Usar fsck como undo. No mueve HEAD. Recuperar un commit es reflog.

Receta (60 segundos)

Solo en un worktree propio, cuando un comando git ya falló con objeto missing o sospechas corrupción:

git status -sb
git fsck --no-dangling
echo $?
git rev-parse HEAD

• 0 y HEAD igual: object database sano. Reporta “fsck ok” y para.
• dangling / unreachable en stdout con exit 0: ruido default, no alarma. No lances gc ni prune.
• missing / hash mismatch / exit 1: reporta la línea. No borres objetos. No --lost-found.
• 128: no hay repo. No reintentes con --full.
• 129: opción desconocida. No añadas flags de gc.

Cierre = el exit code. Cero commit. Cero push a main. Cero “ahora --lost-found”.

fsck vs gc vs prune vs cat-file

gc es housekeeping: --auto --quiet. Cero --aggressive. Cero --prune=now. fsck no comprime nada.

git prune (man git-prune(1), HTTP 200) borra sueltos inalcanzables. El man: en la mayoría de casos corre gc, que ya llama prune con gracia de 2 weeks. Un agente no lo dispara porque fsck imprimió dangling.

cat-file -e pregunta un SHA: 0 existe, 1 no. fsck recorre el grafo. No intercambies uno por el otro.

clean opera el working tree. fsck no lista untracked.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. fsck no es gc: diagnóstico del object database, no housekeeping.