git repack para coding agents: compactar packs, no housekeeping a pelo

git repack empaqueta objetos que aún no viven en un pack y puede reorganizar packs existentes. El man (git-repack(1); git-scm.com/docs/git-repack 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): Pack unpacked objects in a repository. SYNOPSIS: git repack [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx].

Un pack es a collection of objects, individually compressed, with delta compression applied, stored in a single file, with an associated index file. Reduce carga en mirrors, backups y disco. Eso es object database. No toca el working tree ni el índice ni HEAD.

No es gc. gc es porcelain de housekeeping: empaqueta, recorta reflog, rerere, worktrees viejos y ya llama a repack cuando toca. El man de gc: --aggressive pasa -f a git-repack (tira deltas y los recalcula) y It's probably not worth it. Un agente que “repackea a pelo” salta la gracia de gc (gc.auto, gc.autoPackLimit, pre-auto-gc, gc.log).

Tampoco es count-objects. count-objects mira (-v para count / size / in-pack). El man de count-objects: to help you decide when it is a good time to repack. Decidir no es correr git-repack.

Ni prune: prune borra sueltos inalcanzables. -d en repack, después de empacar, corre git prune-packed para borrar sueltos que ya están en un pack. Distinto verbo, distinto riesgo.

Ni maintenance. maintenance orquesta tareas (incremental-repack, loose-objects, commit-graph). El agente pulsa run --auto --quiet, no elige el packer.

Contrato: no corras git repack autónomo. Housekeeping = gc --auto --quiet o maintenance run --auto --quiet. Si el humano pide compactar packs en tu worktree: git repack -d -q. Cero -a. Cero -A. Cero -f / -F. Cero --cruft-expiration. Cero --filter.

Qué hace (y qué no)

Sin flags, combine all objects that do not currently reside in a "pack", into a pack. Incremental: solo sueltos. HEAD igual. Working tree igual.

-d: After packing, if the newly created packs make some existing packs redundant, remove the redundant packs. Also run git prune-packed to remove redundant loose object files. Es el único extra razonable si ya vas a empacar: no dejes el pack viejo y el nuevo.

-a: Instead of incrementally packing the unpacked objects, pack everything referenced into a single pack. El man: Especially useful when packing a repository that is used for private development. Use with -d. También: users fetching over dumb protocols will have to fetch the whole new pack. Un agente no decide que el clone del humano es “private development” ni que nadie usa HTTP tonto. -a es caro, reescribe el layout de packs y puede romper fetches incrementales.

-A: igual que -a, salvo con -d: any unreachable objects in a previous pack become loose, unpacked objects, instead of being left in the old pack. Esos sueltos se podan en el próximo gc. Un agente no “suelta basura a propósito”.

--cruft: con -d, inalcanzables van a un cruft pack (en vez de soltarlos). --cruft-expiration=<approxidate> Expire unreachable objects older than <approxidate> immediately. Eso es prune disfrazado. Cero.

-f pasa --no-reuse-delta a pack-objects. -F pasa --no-reuse-object. Son el corazón de gc --aggressive. El man de gc: no vale la pena para casi nadie. Un agente no “recalcula deltas para ayudar”.

-q / --quiet: sin progreso en stderr. Si corres, corre quieto.

-n: Do not update the server information with git update-server-info. Solo importa si publicas el repo por HTTP/FTP tonto. Un agente no toca catálogos de servidor.

--window default 10, --depth default 50, máximo 4095. Subirlos a lo bestia come RAM (--window-memory) y profundiza deltas. Un agente no tunnea pack.*.

--max-pack-size: mínimo 1 MiB; varios packs y prevents the creation of a bitmap index. El man: may result in a larger and slower repository.

--filter=<filter-spec> saca objetos a otro pack. WARNING del man: si ese pack no es accesible, the repo can become corrupt. Cero filtros, cero --filter-to.

-b / --write-bitmap-index solo tiene sentido con -a/-A/-m. -m / --write-midx escribe multi-pack index. Son perillas de servidor, no de un coding agent en un worktree.

--keep-pack=<pack-name> excluye un pack (como un .keep). Un agente no adivina qué pack “hay que conservar”.

-g / --geometric=<factor> reorganiza para una progresión geométrica de tamaños. Es la estrategia incremental-repack de maintenance. No la dispares a mano.

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

• git repack -q: 0. rev-parse HEAD igual. status -sb sin cambios.
• git repack -d -q: 0. HEAD igual.
• git repack -a -d -q: 0. HEAD igual. El man: pack único de todo lo referenciado; no es el default autónomo.
• git repack --help (vía git help -m repack): documenta -a/-A/-d/-f/-F/--cruft.

Por qué un agente no “repackea para ayudar”

Porcelain que escribe (git add, git fetch, git commit) ya dispara git gc --auto cuando hay demasiados sueltos (gc.auto default 6700) o demasiados packs (gc.autoPackLimit default 50). Ese camino respeta pre-auto-gc, gc.log y el lock del object database.

git repack no consulta esa heurística. Corre ya. En un clone grande, -a -d -f puede ocupar CPU y disco minutos y, con dumb HTTP, forzar a cada fetch a bajar el pack entero. En un worktree ajeno, dos procesos que escriben packs a la vez son el escenario que gc --prune=now también advierte: corrupción.

Si count-objects -v muestra count alto, el siguiente paso no es repack. Es reportar el número y, si el humano pide housekeeping, git gc --auto --quiet. Si --auto sale 0 sin trabajar, no hay nada que compactar. Inventar -a -f “porque el número impresiona” es el mismo anti-patrón que gc --aggressive.

Tabla: comando → efecto → riesgo

Comando	Qué toca	Riesgo para un agente
git count-objects -v	nada (lee)	bajo; no empaca
git gc --auto --quiet	object DB si la heurística lo pide	contrato de housekeeping
git maintenance run --auto --quiet	tareas incrementales	contrato de scheduler
git repack -d -q	sueltos → pack; borra packs redundantes + prune-packed	solo si el humano lo pide en tu worktree
git repack -a -d	un pack con todo lo referenciado	caro; dumb HTTP baja el pack entero
git repack -A -d	igual + suelta inalcanzables	prune diferido; no autónomo
git repack -f / -F	no reusa deltas/objetos	el --aggressive de gc
git repack --cruft-expiration=now -d	borra inalcanzables ya	prune disfrazado
git repack --filter=...	parte el object DB	corrupción si el pack filtrado no se sirve

Prohibido en autónomo

• git repack en el clone del humano. El object database es compartido con su git status, su IDE y su fetch.
• -a / -A “para dejar un solo pack”. El man reserva -a a desarrollo privado y avisa del dumb protocol.
• -f / -F / --window enorme / --depth enorme. Recalcular deltas no es un favor.
• --cruft-expiration, --expire-to, --unpack-unreachable. Eso es política de expiry, no compactación.
• --filter / --filter-to. El WARNING de corrupción es del man, no de un blog.
• -b / -m / --pack-kept-objects / --keep-pack / --geometric sin que el humano administre el servidor.
• Reescribir repack.useDeltaBaseOffset, pack.windowMemory, pack.packSizeLimit. Son perillas del clone.
• Encadenar repack y gc y maintenance run en el mismo tick. gc y maintenance documentan lock distinto; dos packers concurrentes son el fallo.
• Confundir prune-packed con prune. prune-packed borra sueltos duplicados en un pack. prune borra inalcanzables. -d ya llama al primero.
• Confundir con clean. clean borra untracked. repack no mira el working tree.

Receta (60 segundos)

Solo en un worktree propio, y solo si el humano pidió compactar packs (no porque count sea alto):

git status -sb
git count-objects -v
git gc --auto --quiet
echo $?
git rev-parse HEAD

• 0 y HEAD igual: listo. Reporta “gc --auto” y para. No sigas con repack.
• Si el humano insiste en el packer: git repack -d -q · echo $? · git rev-parse HEAD. Cero -a. Cero -f.
• 128: no hay repo. No reintentes con -a.
• 129: opción desconocida. No inventes --aggressive (eso es de gc).

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

repack vs gc vs prune vs count-objects

gc: --auto --quiet; cero --aggressive; cero --prune=now. Es quien debe llamar a repack.

maintenance: run --auto --quiet; cero start/register. incremental-repack es una tarea suya, no un git repack -a tuyo.

prune: -n primero; cero a pelo / --expire=now.

count-objects: -v. Diagnóstico. Cero git-repack “porque el número es alto”.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. repack es el packer; el agente no lo dispara: deja que gc --auto decida.