git index-pack para coding agents: idx de un .pack, no unpack ni --stdin a ciegas

git index-pack construye el índice de un packed archive ya existente: lee un .pack, escribe el .idx (y opcionalmente un reverse-index .rev) y deja ese par listo para objects/pack/. El man (git-index-pack(1); git-scm.com/docs/git-index-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): Build pack index file for an existing packed archive. SYNOPSIS:

git index-pack [-v] [-o <index-file>] [--[no-]rev-index] <pack-file>
git index-pack --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
                  [--[no-]rev-index] [<pack-file>]

Eso es un pack concreto en disco (primera forma) o un stream que se materializa (segunda). No recorre refs. No mueve HEAD. No crea el .pack (eso es pack-objects). No valida un idx ya hecho (eso es verify-pack). No explota el pack a objetos sueltos (git unpack-objects).

Contrato: pasa el .pack. Cierre = exit code + el hash de stdout. Cero -v al contexto. Cero --stdin autónomo. Cero --fix-thin. Cero unpack porque “falta el idx”.

Qué hace (y qué no)

Sin flags, con un .pack que termina en .pack: construye el .idx al lado, sustituyendo la extensión. NOTES del man: Once the index has been created, the hash that goes into the name of the pack/idx file is printed to stdout. En Git 2.50.1 / Apple Git-155, sobre un pack de 3 objetos generado con pack-objects --non-empty -q, stdout fue solo ese SHA (40 hex) y el exit 0. Reindexar el mismo .pack (idx ya presente) volvió a imprimir el mismo hash y exit 0: no es un error.

-v: Be verbose about what is going on, including progress status. En el mismo pack: barra Indexing objects: N% y luego el hash. El extra es ruido de progreso. Para un agente, -v es peor: no añade un veredicto; ensucia el cierre.

-o <index-file>: Write the generated pack index into the specified file. Sin -o, el nombre sale del .pack. Si el archivo no termina en .pack, el programa falla. No inventes la extensión.

--[no-]rev-index: generate a reverse index (a .rev file). Toma precedencia sobre pack.writeReverseIndex. En el experimento local, pack-objects ya escribió .rev; index-pack sin este flag no lo tocó. No lo pidas “por higiene”.

--stdin: the pack is read from stdin instead and a copy is then written to <pack-file>. Si omites <pack-file>, the pack is written to objects/pack/ directory of the current Git repository. El man pide considerar --keep para evitar una race con git repack. Eso escribe en el object store. Un coding agent no lo hace solo.

--fix-thin: Fix a "thin" pack produced by git pack-objects --thin … by adding the excluded objects. This option only makes sense in conjunction with --stdin. pack-objects ya veta --thin en autónomo: un thin pack violates the packed archive format. No “arregles” un thin que tú no debiste crear.

--keep / --keep=<msg>: crea un .keep vacío (o con mensaje) antes de mover el idx a su destino. Es un lock contra repack. Útil en receive-pack; inútil si no estás ingiriendo un pack por stdin.

--strict / --fsck-objects: mueren si el pack trae objetos rotos (strict también mira links). No son un fsck del repo. No los uses como “fsck rápido del pack”.

--threads, --max-input-size, --object-format, --promisor, --index-version, --progress-title, --check-self-contained-and-connected: test suite, internal use o clone parcial. SYNOPSIS autónomo: el .pack y nada más.

Límites del agente (no hagas esto)

• --stdin sin que el humano pida ingerir un pack. Escribe en objects/pack/ o en el path que pases. Race con repack.
• --fix-thin “por si el pack es thin”. Solo tiene sentido con --stdin. pack-objects autónomo ya prohíbe --thin.
• -v al contexto. El hash de stdout basta. El progreso no es el veredicto.
• git unpack-objects porque “index-pack no me dio blobs”. unpack lee stdin y expande a loose. Sobre un pack que ya vive en el repo, nothing will be unpacked. Distinta herramienta, distinto daño.
• Encadenar repack o pack-objects porque el idx “ya está”. index-pack no compacta.
• Tratar el hash de stdout como un commit. Es el nombre del pack/idx, no un SHA de HEAD.
• --object-format=sha256 a ciegas. This option cannot be used with --stdin. Y el repo del humano casi seguro es SHA-1.
• --strict como sustituto de fsck. fsck mira el grafo y las refs. index-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 (fetch a medias, bundle, archivo suelto).
• Inventar --stat-only, -s, --verbose estilo verify-pack. SYNOPSIS de index-pack: -v, -o, --rev-index, --stdin.

Receta (60 segundos)

Solo en un worktree propio, y solo si un fetch, un bundle o un error ya nombró un .pack fuera del object store (o un pack huérfano cuyo idx falta):

git status -sb
git index-pack /ruta/al/pack-<id>.pack
echo $?
git rev-parse HEAD

En un worktree vinculado, el object database vive en git rev-parse --git-common-dir. Si el pack ya está en objects/pack/ con idx, no lo reindexes “por si acaso”: verify-pack -s sobre el .idx es el diagnóstico.

• 0 + 40 hex en stdout: el idx se escribió (o se reescribió). Reporta el hash. Cero -v.
• 128: no hay repo o el path no resolvió. Distinto de verify-pack: index-pack sin repo y con path absoluto sí puede indexar un .pack suelto si el cwd no importa; si falla, reporta el fatal y para.
• 129: usage u opción desconocida. No añadas flags de fsck ni de verify-pack.
• Fatal does not end with .pack: el path no termina en .pack. No improvises -o para “arreglarlo” salvo que el humano pida un idx con otro nombre.

Cierre = el exit code y el hash. Cero commit. Cero push a main. Cero --stdin “para dejarlo en objects/pack”.

index-pack vs pack-objects vs verify-pack vs unpack

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

verify-pack lee un .idx y comprueba el .pack. Diagnóstico: -s. Cero -v dump. No escribe idx. Si el par ya está en objects/pack/, verifica; no reindexes.

git unpack-objects lee un .pack por stdin y escribe objetos loose. Objects that already exist … will not be unpacked. No es el inverso de index-pack. No lo uses para “ver qué hay dentro”.

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

fsck diagnostica el object database y las refs. Un idx recién escrito no sustituye fsck.

FAQ

¿index-pack verifica el pack? Construye el idx leyendo el pack. No es el histograma de verify-pack -s. Si el pack ya tiene idx y quieres diagnóstico, verify-pack. Si el idx falta, index-pack.

¿--stdin es “más correcto”? Es el camino de receive-pack / fetch: copia el stream al object store. El man avisa la race con repack y sugiere --keep. Para un agente que no está recibiendo un pack, es un write al repo. Primera forma: el archivo.

¿Puedo pasar el .idx? El SYNOPSIS pide <pack-file>. Pasa el .pack. verify-pack pide el .idx. No los intercambies.

¿El hash de stdout es el pack o un commit? El man: the hash that goes into the name of the pack/idx file. En el experimento 2.50.1 coincidió con el pack-<hash>.pack que había escrito pack-objects. No es HEAD.

¿--fix-thin repara un pack corrupto? No. Restaura objetos base omitidos a propósito por pack-objects --thin. Corrupción es otro problema (y no se “arregla” con thin).

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. index-pack indexa un .pack; el agente reporta el hash, no ingiere el stream.