git show-index para coding agents: dump del .idx, no verify-pack

git show-index vuelca el índice de un packed archive. El man (git-show-index(1); git-scm.com/docs/git-show-index 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): Show packed archive index. SYNOPSIS: git show-index [--object-format=<hash-algorithm>] < <pack-idx-file>.

Eso es stdin. Lee el .idx (creado con pack-objects o index-pack) desde la entrada estándar y imprime una línea por objeto. No abre el .pack. No recorre refs. No mueve HEAD. No escribe nada.

El man lo contrapone a verify-pack: you can get more information on a packfile by calling git-verify-pack(1). However, as this command considers only the index file itself, it's both faster and more flexible. Más rápido porque no valida el pack. Más flexible porque no exige el par .idx+.pack al lado. El precio: un dump, no un veredicto.

Contrato para un coding agent: redirige el .idx a stdin. Cierre = exit code + wc -l (o head). Cero dump al contexto. Cero path en argv. Cero --object-format a ciegas.

Qué imprime (y qué no)

DESCRIPTION: una línea por objeto, dos o tres columnas separadas por espacio:

• 1. offset en bytes del objeto dentro del packfile
• 2. object id
• 3. si el índice es versión 2 o mayor, CRC32 de los datos del objeto

El orden es el del archivo índice, que should be (in a correctly constructed file) sorted by object id. No es el orden de aparición en el .pack.

Verificado 2026-09-06 (Git 2.50.1 / Apple Git-155) sobre un .idx real del object store (803 objetos, v2):

Input	Stdout	Exit
(sin stdin / TTY)	fatal: unable to read header	128
path en argv (git show-index file.idx)	fatal: unable to read header	128
git show-index -- file.idx	igual: lee stdin, ignora el path	128
stdin vacío	fatal: unable to read header	128
stdin basura (not-an-idx)	fatal: unable to read index	128
--unknown	unknown option, usage	129
< file.idx	803 líneas offset oid (crc32)	0
--object-format=sha1 < file.idx	mismas 803 líneas	0
--object-format=sha256 < file.idx (idx SHA-1)	fatal: unable to read sha1 703/803	128
--object-format=md5	fatal: Unknown hash algorithm	128
--no-object-format < file.idx	803 líneas	0
cd /tmp + < file.idx absoluto	803 líneas (no hace falta repo)	0

Primera línea del experimento: 240045 00611007e634405a179b0a255064097763ebbbed (49a41de4) — tres campos, 59 bytes con newline. Los OID salen ordenados. Eso cabe en un head -3. Las 803 líneas no caben en el contexto del modelo.

-h / usage: git show-index [--object-format=<hash-algorithm>] < <pack-idx-file>. El binario también lista --[no-]object-format. El SYNOPSIS del man es el contrato. Un agente no elige SHA-256 “por si acaso”.

Límites del agente (no hagas esto)

• Pasar el .idx como argv. SYNOPSIS: redirección. En 2.50.1 el path en argv (con o sin --) dejó stdin vacío y salió 128 unable to read header. No es verify-pack, que sí pide <pack>.idx en la línea de comandos.
• Volcar stdout al LLM. 803 líneas en un pack chico; un repo grande son decenas de miles. Cierre = echo $? y wc -l. Si hace falta una muestra: head -3.
• --object-format=sha256 sobre un idx SHA-1. El default es el algoritmo del repo (extensions.objectFormat) o SHA-1 fuera de un repo. El experimento: unable to read sha1 703/803, exit 128. No “pruebes el otro hash”.
• --object-format inventado (md5, sha512). Unknown hash algorithm, 128.
• Encadenar verify-pack -v porque “show-index no validó el pack”. El man ya dice que verify-pack da más información. El contrato de verify-pack es -s, no -v.
• Correr index-pack porque “el dump se ve raro”. index-pack escribe un .idx. show-index lee.
• unpack-objects para “ver el contenido”. unpack lee un .pack por stdin y expande a loose. Distinta herramienta, distinto daño.
• repack / pack-objects porque el índice “está bien” o “está mal”. show-index no compacta ni reescribe.
• Tratar el offset como un SHA o el CRC como un object id. Columna 1 = byte offset en el packfile. Columna 2 = object id. Columna 3 = CRC32 entre paréntesis.
• Correrlo sobre el clone del humano “por higiene”. Solo worktree propio, y solo si un .idx concreto ya es el problema (bundle, pack suelto, idx huérfano).
• Inventar -v, -s, --stat-only. Eso es verify-pack. show-index no tiene flags de histograma.

Receta (60 segundos)

Solo en un worktree propio, y solo si un fetch, un bundle o un error ya nombró un .idx:

git status -sb
git show-index < /ruta/al/pack-<id>.idx | wc -l
echo $?
git rev-parse HEAD

Si el idx vive en el object store del worktree vinculado: git rev-parse --git-path objects/pack. No copies packs al working tree para “inspeccionarlos”.

• 0 + un entero en wc -l: el idx se parseó. Reporta el conteo. Cero dump.
• 128 unable to read header: stdin vacío, TTY, o el path fue a argv. Redirige el archivo. No añadas flags.
• 128 unable to read index: stdin no es un idx (basura, .pack por error, truncado). Pasa el .idx, no el .pack.
• 128 unable to read sha1 N/M o Unknown hash algorithm: --object-format no coincide. Quita el flag.
• 129: usage u opción desconocida. SYNOPSIS: solo --object-format.

Cierre = el exit code y el conteo. Cero commit. Cero push a main. Cero git show-index archivo.idx “porque verify-pack también recibe path”.

show-index vs verify-pack vs index-pack vs pack-objects

verify-pack valida un .idx y el .pack. Diagnóstico autónomo: -s (histograma de deltas). Cero -v dump. Pide el .idx en argv. Si quieres saber si el par está sano, verify-pack. Si quieres listar offsets del índice sin abrir el pack, show-index.

index-pack escribe el .idx a partir de un .pack. Cierre = hash en stdout. Cero --stdin autónomo. show-index no construye índices.

pack-objects escribe el .pack. Contrato autónomo: --non-empty -q + base-name fuera del object store. Cero --thin / --stdout / --filter. show-index no empaca.

unpack-objects lee un pack por stdin y materializa objetos loose. show-index lee un idx por stdin y no toca objects/.

fsck mira el grafo y las refs. Un dump de idx no dice que el repo esté sano.

count-objects cuenta sueltos y packs. No abre un .idx concreto.

FAQ

¿Puedo pasar el path como argumento? No. SYNOPSIS: < <pack-idx-file>. En Git 2.50.1 el argv se ignora como archivo; sin stdin sale 128 unable to read header. verify-pack sí toma <pack>.idx.... No copies ese patrón.

¿show-index verifica el pack? No. considers only the index file itself. CRC32 en la tercera columna es del objeto según el idx, no una prueba del .pack en disco. Para validar el par: verify-pack -s.

¿Por qué no meter todo el dump en el reporte? Un pack de prueba ya son cientos de líneas; un monorepo, órdenes de magnitud más. El man no ofrece un modo resumido. El resumen es wc -l + head.

¿Hace falta un repositorio? No. cd /tmp + redirección de un .idx absoluto salió 0 con las mismas 803 líneas. El default de --object-format fuera de un repo es SHA-1.

¿--object-format es obligatorio? No. Úsalo solo si el humano ya sabe que el idx no es el hash del repo. No lo pruebes a ciegas: un SHA-256 sobre idx SHA-1 aborta a mitad (unable to read sha1 N/M).

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. show-index vuelca un .idx por stdin; el agente reporta el conteo, no el dump.