git verify-pack para coding agents: validar un pack, no volcar el object database

git verify-pack valida un packed Git archive: lee cada .idx de la línea de comandos y comprueba ese índice y el .pack correspondiente. El man (git-verify-pack(1); git-scm.com/docs/git-verify-pack HTTP 200, last-modified 2026-08-31; last updated in 2.50.0; pie del man local Git 2.50.1.428.g0e8243, 2025-07-22; binario Git 2.50.1 / Apple Git-155): Validate packed Git archive files. SYNOPSIS: git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx....

Eso es un pack concreto. No recorre refs, ni el índice, ni HEAD. No cuenta sueltos. No reescribe el object database.

No es fsck. fsck Verifies the connectivity and validity of the objects in the database: hashes, alcanzabilidad, dangling, refs. verify-pack no mira HEAD ni refs/. Un pack “ok” no dice que el grafo esté sano.

Tampoco es count-objects. count-objects Count unpacked number of objects and their disk consumption. Te da count / in-pack / size-pack. No abre un .idx ni comprueba CRC de un pack.

Ni repack. repack escribe packs. verify-pack lee. El contrato autónomo de repack es no correrlo; el de verify-pack es no volcar -v al LLM.

Contrato: pasa el .idx. Cierre = exit code + histograma -s si hace falta. Cero -v al contexto. Cero dump de objetos. Cero git-repack porque el pack “está bien”.

Qué hace (y qué no)

Sin flags, con un .idx existente: verifica índice y pack. En Git 2.50.1 el caso sano sale 0 y stdout vacío. El man no promete un “ok” salvo con -v.

-s / --stat-only: Do not verify the pack contents; only show the histogram of delta chain length. Líneas tipo non delta: N objects y chain length = k: M objects. Es el diagnóstico útil: cabe en el reporte. El man añade With --verbose, the list of objects is also shown. En el binario 2.50.1 / Apple Git-155, -s -v no listó objetos: mismo histograma que -s (8 líneas en el pack de prueba). No dependas de -s -v para un dump; y no lo pidas.

-v / --verbose: After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. Formato del man:

• no deltificado: object-name type size size-in-packfile offset-in-packfile
• deltificado: lo mismo + depth base-object-name

Al final, una línea <path>.pack: ok y el histograma. En el pack de prueba: 309 líneas. Eso es un dump. Un agente no lo relee entero.

--: Do not interpret any more arguments as options. Úsalo si un path empieza por -.

El usage del binario también lista --[no-]object-format <hash>. El SYNOPSIS del man web no. Un agente no elige SHA-1 vs SHA-256 “por si acaso”.

SYNOPSIS: <pack>.idx.... Pasa el índice. Varios .idx se aceptan. No pases un .pack y asumas que silencio + 0 es la misma prueba.

Verificado 2026-09-06 (Git 2.50.1 / Apple Git-155). Worktree propio, working tree limpio, un .idx del object database compartido:

• sin args: 129, usage: git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
• git verify-pack <pack>.idx: 0. stdout vacío. rev-parse HEAD igual. status -sb sin cambios.
• git verify-pack -s <pack>.idx: 0. Histograma (non delta + chain length = 1..7 en el pack de prueba). HEAD igual.
• git verify-pack --stat-only <pack>.idx: 0. Idéntico a -s.
• git verify-pack -v <pack>.idx: 0. Lista de objetos + histograma + <pack>.pack: ok (309 líneas en el pack de prueba). HEAD igual. No lo vuelques al contexto.
• git verify-pack -s -v <pack>.idx: 0. En este binario, 8 líneas de histograma, sin lista de objetos.
• dos .idx: 0. Histogramas concatenados.
• .idx inexistente: 1, fatal: Cannot open existing pack file '…'
• --foo: 129, unknown option `foo'
• git -C /tmp verify-pack <pack>.idx: 0. No exige cwd de repo: el path del .idx basta.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
¿Este pack está íntegro?	git verify-pack path/to/pack-….idx	-v y pegar 300 SHA al LLM
Histograma de deltas	git verify-pack -s path/to/pack-….idx	parsear offsets de -v
¿El repo está sano?	fsck	un pack “ok” como fsck
¿Cuántos sueltos / packs?	count-objects -v	verify-pack como inventario
Housekeeping	gc --auto --quiet	repack porque el pack verificó

Prohibido en autónomo:

• -v a un log que el modelo relee. Cierre = exit code, o el histograma -s.
• Inventar --aggressive, --full, --unreachable. Eso es de fsck / gc. SYNOPSIS: -v y -s.
• Encadenar repack o pack-objects porque el pack “está bien” o porque chain length impresiona. verify-pack no empaca.
• Tratar chain length = 7 como licencia para -f / --no-reuse-delta. Profundidad de delta ≠ corrupción.
• rm del .pack / .idx si el exit no es 0. Reporta el fatal y para. Restaurar packs no es git restore.
• Correrlo “sobre todo .git/objects/pack/*.idx” y concatenar -v. Varios idx con -s ya son ruido; con -v es un dump del object database.
• --object-format a ciegas. El man canónico no lo pone en el SYNOPSIS.
• Confundirlo con count-objects. size-pack no valida CRC.
• Confundirlo con fsck. fsck mira el grafo. verify-pack mira un archivo pack.
• Correrlo en el clone del humano “por higiene”. Solo worktree propio, y solo si un pack concreto ya es el problema.

Receta (60 segundos)

Solo en un worktree propio, y solo si un fetch, un clone o un error ya nombró un pack:

git status -sb
git verify-pack -s .git/objects/pack/pack-<id>.idx
echo $?
git rev-parse HEAD

En un worktree vinculado, el object database vive en git rev-parse --git-common-dir (no en el GIT_DIR corto del worktree). Si objects/pack no está ahí, usa $(git rev-parse --git-common-dir)/objects/pack/<name>.idx.

• 0 y histograma: el par idx+pack se pudo leer. Reporta non delta y el máximo chain length. Cero -v.
• 0 sin -s: pack verificado, stdout vacío. Suficiente.
• 1: Cannot open existing pack file. Path mal, idx huérfano o pack ausente. No reintentes con -v.
• 128: no hay repo y el path no resolvió. Distinto de fsck: verify-pack puede correr con cwd fuera si el .idx es absoluto (verificado: git -C /tmp + path absoluto → 0).
• 129: usage u opción desconocida. No añadas flags de fsck.

Cierre = el exit code y, si usaste -s, el histograma. Cero commit. Cero push a main. Cero “ahora un pack único”.

verify-pack vs fsck vs count-objects vs repack

fsck diagnostica el object database y las refs. dangling no es error. Un pack verificado no sustituye fsck.

count-objects: -v. Inventario de sueltos y packs. Cero git-repack porque count es alto. Tampoco verify-pack.

repack: no autónomo. Si el humano pide compactar: -d -q. Cero -a/-f. verify-pack no es el paso previo obligatorio.

gc: --auto --quiet. Es housekeeping. verify-pack no lo dispara.

FAQ

¿-v es “más correcto”? Verifica igual y además lista cada objeto. El man lo dice: After verifying the pack, show the list. El extra es el dump. Para un agente, -v es peor: 300 SHA no caben en el cierre.

¿--stat-only verifica el pack? El man: Do not verify the pack contents. -s es histograma, no la prueba de integridad. Si dudas del archivo, corre sin -s. Si solo quieres cadenas de delta, -s.

¿Un chain length alto está corrupto? No. Es profundidad de delta dentro del pack. Corrupción es exit ≠ 0 o un fatal. Recalcular deltas es -f de repack, prohibido en autónomo.

¿Puedo pasar el .pack? El SYNOPSIS pide .idx. Pasa el índice. No improvises la extensión.

¿Sirve como fsck rápido? No. fsck sigue refs, trees y blobs del grafo. verify-pack no sabe si HEAD apunta a un commit huérfano.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. verify-pack valida un packed archive; el agente reporta el exit, no el inventario de objetos.