git multi-pack-index para coding agents: un índice de packs, no gc

git multi-pack-index escribe y verifica el multi-pack-index (MIDX). El man (git-multi-pack-index(1); git-scm.com/docs/git-multi-pack-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): Write and verify multi-pack-indexes. SYNOPSIS: git multi-pack-index [--object-dir=<dir>] [--[no-]bitmap] <sub-command>.

El archivo vive en $GIT_DIR/objects/pack/multi-pack-index (o, si es cadena incremental, en capas bajo objects/pack/). No es un pack. No es un .idx de un pack. No mueve HEAD. core.multiPackIndex default true: Git lee el MIDX si existe (git-config(1): Use the multi-pack-index file to track multiple packfiles using a single index). Escribirlo es otro verbo.

No es repack. repack Pack unpacked objects in a repository: reescribe packs. MIDX indexa packs que ya existen. Tampoco es pack-objects: pack-objects crea un packed archive. Ni verify-pack: verify-pack valida un .idx+.pack. MIDX mira el índice entre packs.

No es gc. gc Cleanup unnecessary files and optimize the local repository y, con gc.autoPackLimit (default 50), consolida packs. Tampoco es maintenance: el task incremental-repack repacks the object directory using the multi-pack-index feature — primero expire, luego repack del MIDX. El orquestador no es este comando.

Contrato: git multi-pack-index verify. Cero write autónomo. Cero expire. Cero repack. Cero --object-dir ajeno. Cero --bitmap / --incremental / --stdin-packs. Cero en el clone del humano salvo que el humano lo pida.

Qué hace (y qué no)

Cuatro subcomandos. Sin subcomando el binario 2.50.1 sale 129: error: need a subcommand y el usage. No hay “modo default” que liste packs.

Subcomando	Qué hace	Autónomo
verify	Verify the contents of the MIDX file.	sí, si ya hay un problema de packs
write	Write a new MIDX file.	no
expire	borra packs trackeados por el MIDX sin objetos referenciados (salvo .keep y cruft) y reescribe el MIDX	no
repack	crea un pack nuevo con objetos de packs pequeños referenciados por el MIDX	no

write opciones (man + -h del binario): --preferred-pack=<pack>, --[no-]bitmap, --stdin-packs, --refs-snapshot=<path>, --incremental. --incremental Write an incremental MIDX file containing only objects and packs not present in an existing MIDX layer y es incompatible con --bitmap. --object-dir=<dir>: must be an alternate of the current repository. No es un path libre.

expire y repack son incompatibles con MIDX incremental (nota del man). repack --batch-size=0 create a pack containing all objects referenced by the multi-pack-index. Un agente no elige batch size.

--[no-]progress aplica a write, verify, expire y repack. Un agente no fuerza progress para “verse ocupado”.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
¿El MIDX está íntegro?	git multi-pack-index verify	write “por si no existe”
¿Cuántos packs hay?	count-objects -v	MIDX como inventario
¿Este .pack está sano?	verify-pack -s + .idx	verify del MIDX como CRC de un pack
Housekeeping	gc --auto --quiet o maintenance que el humano ya registró	expire/repack del MIDX
Empaquetar sueltos	repack si el humano pide -d -q	multi-pack-index repack

Prohibido en autónomo:

• write. Crea o reescribe objects/pack/multi-pack-index. En sandbox 2.50.1, con un pack presente: 0, archivo nuevo, HEAD igual. Sin packs: 1, error: no pack files to index. No “arregles” el 1 empacando.
• expire. El man: Delete the pack-files that are tracked by the MIDX file, but have no objects referenced by the MIDX. Eso borra packs. Cero autónomo. Cero porque verify pasó.
• repack (el subcomando de MIDX). No es repack. Reescribe packs vía el MIDX. --batch-size=0 empaqueta todo lo referenciado. Cero.
• --object-dir ajeno. En sandbox, --object-dir /tmp write → 128, fatal: could not find object directory matching /private/tmp. El man exige un alternate del repo actual.
• --bitmap, --preferred-pack, --refs-snapshot, --stdin-packs, --incremental. Son de write. Un agente no elige bitmap ni capa incremental.
• Encadenar pack-objects o repack porque “no hay MIDX”. verify 0 sin archivo (sandbox y este worktree: stdout vacío, HEAD igual) no es un error.
• core.multiPackIndex=false para “arreglar” un verify. Eso es config. Si está disabled, Git deja de leer el archivo; no es licencia para borrarlo.
• Correrlo en el clone del humano “por higiene”. Solo worktree propio, y solo si packs/MIDX ya son el problema.

Receta (60 segundos)

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

git status -sb
git multi-pack-index verify
echo $?
git rev-parse HEAD

En un worktree vinculado, el object database vive en git rev-parse --git-common-dir. El MIDX, si existe, está en $(git rev-parse --git-common-dir)/objects/pack/multi-pack-index.

• 0 y stdout vacío: el MIDX se pudo leer, o no había nada que verificar. Reporta el exit. Cero write “para dejarlo listo”.
• 1: no pack files to index es de write, no de verify. Si verify falla con otro fatal, reporta el stderr y para. No borres packs.
• 128: --object-dir que no es alternate, o no hay repo. No reintentes con /tmp ni con el GIT_DIR de otro clone.
• 129: sin subcomando, opción desconocida (--foo → unknown option `foo') o subcomando inventado (foo → unknown subcommand: `foo'). No añadas flags de gc.

Cierre = el exit code. Cero commit. Cero push a main. Cero “ahora un pack único”.

Verificado 2026-09-06 (Git 2.50.1 / Apple Git-155). Repo throwaway, working tree limpio, un pack de repack -d -q:

• sin args: 129, need a subcommand
• verify sin MIDX: 0. stdout vacío. HEAD igual.
• write: 0. Crea objects/pack/multi-pack-index. HEAD igual. No autónomo.
• verify con MIDX: 0. stdout vacío.
• write --object-dir /tmp: 128, could not find object directory matching
• expire / repack con MIDX de un pack: 0. No es licencia. HEAD igual.
• write sin packs: 1, no pack files to index.
• --foo: 129. foo como subcomando: 129.

Este worktree (guia-git-multi-pack-index-coding-agents): verify → 0, HEAD 14b862c2 igual, status -sb limpio. El archivo multi-pack-index ya existía en el object store compartido. Cero write.

MIDX vs verify-pack vs repack vs gc vs maintenance

verify-pack valida un packed archive (.idx). MIDX verify valida el índice entre packs. Un MIDX “ok” no dice que un .pack concreto tenga CRC sano.

repack: no autónomo. Si el humano pide compactar: -d -q. Cero -a/-f. multi-pack-index repack no es ese comando.

pack-objects: plumbing de un pack. MIDX no empaca objetos sueltos.

gc: --auto --quiet. Puede consolidar packs por gc.autoPackLimit. No dispares MIDX expire porque gc “debería”.

maintenance: run --auto --quiet. El task incremental-repack sí llama multi-pack-index expire y luego repack. Eso es el orquestador, con lock del object database. Un agente no reproduce esos dos pasos a mano. Cero start/register.

count-objects: -v. Inventario. packs alto no es orden de escribir MIDX.

index-pack: .pack → .idx. El MIDX no sustituye el .idx de cada pack.

FAQ

¿verify 0 sin archivo MIDX es un error? No en 2.50.1: exit 0, stdout vacío. No escribas el índice para “corregir” el silencio.

¿write es seguro porque no mueve HEAD? HEAD no se mueve (verificado). El archivo del object store sí cambia. En el clone del humano eso es mutación. Cero autónomo.

¿Puedo pasar --bitmap “por rendimiento”? write --bitmap pide un MIDX con bitmap multi-pack. El man lo ata a --preferred-pack y, con bitmap, a --refs-snapshot opcional. Incompatible con --incremental. Un agente no elige bitmaps.

¿expire solo borra packs vacíos? Borra packs trackeados por el MIDX sin objetos referenciados, excepto .keep y cruft, y reescribe el MIDX. Incompatible con MIDX incremental. Cero autónomo.

¿Es lo mismo que git repack -m? No. Este comando es el MIDX. repack tiene su propio contrato. No copies flags de uno al otro.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. El MIDX es un índice de packs; el agente verifica, no lo reescribe.