LaughingisLaughing/git-repo-doctor

¿Qué hace git-repo-doctor?

Diagnóstico de solo lectura y asesor de limpieza segura para repositorios Git inflados.

Cuándo usar esta skill

• El directorio .git ha crecido a varios gigabytes.
• Se están acumulando archivos objects/pack/tmp_pack_* o objects/??/tmp_obj_*.
• git count-objects -v muestra un recuento grande de garbage o cientos de miles de objetos sueltos.
• gc.auto=0, o gc / repack / fetch se interrumpen constantemente.
• Un editor o agente de codificación (Codex, Claude Code, Cursor, un indexador de IDE) falla o se queda sin memoria mientras escanea un repositorio.
• El usuario pregunta cómo reducir, limpiar, podar, recolectar basura o recuperar espacio de un repositorio de forma segura.

Cómo ejecutar

Script único de Python 3 sin dependencias. Es estrictamente de SOLO LECTURA.

# Diagnosticar el repositorio que contiene el directorio actual:
python3 scripts/git_repo_doctor.py

# Apuntar a un git dir específico, incluido uno renombrado/deshabilitado:
python3 scripts/git_repo_doctor.py --git-dir /path/to/.git.disabled-xyz

# Salida legible por máquina (analiza esto cuando actúes como agente):
python3 scripts/git_repo_doctor.py --json

# Omitir la sonda de alcanzabilidad remota (sin conexión o red lenta):
python3 scripts/git_repo_doctor.py --no-remote

Qué devuelve

1. Desglose de tamaño - basura definitiva / suelto / paquetes / historial alcanzable / estimación de no alcanzable / margen de disco.
2. Problemas de salud - gc.auto=0, gc.log obsoleto, árbol de trabajo igual a $HOME, Syncthing sincronizando .git, inundación de objetos sueltos, archivos temporales sobrantes.
3. Una recomendación, una de:
   • RUTA A (historial alcanzable pequeño): red de seguridad con bundle, probar que se restaura, luego una eliminación en capas y retrasada.
   • RUTA B (historial sustancial): git maintenance + gc/repack en el lugar; si el disco está justo, eliminar la basura primero.
   • Sugerencia de filter-repo / BFG cuando hay blobs gigantes en el historial alcanzable.
4. Un plan de limpieza listo para copiar y pegar, con capacidad de reversión con puntos de reversión explícitos. El script imprime los comandos y no ejecuta ninguno.

Cómo debe usar el agente la salida

• Ejecuta el script, luego resume el desglose de tamaño, los problemas de salud y la RUTA recomendada para el usuario.
• Presenta el plan impreso pero NO ejecutes ningún comando automáticamente. La limpieza es irreversible; el humano debe confirmar cada paso destructivo.
• Siempre verifica el valor de $GITDIR, asegúrate de que el bundle se cree y verifique, y conserva el bundle hasta que el usuario esté seguro.

Contrato de seguridad

Esta herramienta nunca ejecuta gc, prune, repack, rm, reflog expire, ni ningún comando mutante. Lo único que ejecuta son consultas git de solo lectura y estadísticas del sistema de archivos, todas protegidas por tiempo de espera. Cada acción destructiva existe únicamente como texto en el plan impreso para que un humano lo revise y ejecute.

Lógica de decisión (resumen)

Condición	Recomendación
alcanzable < 1 GiB y < 10% del total	RUTA A: bundle + eliminación/ reconstrucción en capas
alcanzable sustancial, espacio libre amplio	RUTA B: git maintenance + gc/repack en el lugar
alcanzable sustancial, disco justo	eliminar basura primero, luego reempaquetar
pocos objetos empaquetados pero tamaño de paquete enorme	sugerencia de blob gigante (ejecuta git-sizer, considera git-filter-repo)

Consulta README.md para la documentación completa y un informe de ejemplo.