git-repo-doctor

Que fait git-repo-doctor ?

Diagnostic en lecture seule et conseiller de nettoyage sécurisé pour les dépôts Git gonflés.

Quand utiliser cette compétence

• Un répertoire .git a atteint plusieurs gigaoctets.
• Des fichiers objects/pack/tmp_pack_* ou objects/??/tmp_obj_* s'accumulent.
• git count-objects -v affiche un grand nombre de garbage ou des centaines de milliers d'objets en vrac.
• gc.auto=0, ou gc / repack / fetch sont constamment interrompus.
• Un éditeur ou un agent de codage (Codex, Claude Code, Cursor, un indexeur IDE) plante ou fait une OOM lors de l'analyse d'un dépôt.
• L'utilisateur demande comment réduire, nettoyer, élaguer, garbage-collecter ou récupérer de l'espace disque sur un dépôt.

Comment exécuter

Script Python 3 unique, sans dépendance. Il est strictement EN LECTURE SEULE.

# Analyser le dépôt contenant le répertoire courant :
python3 scripts/git_repo_doctor.py

# Cibler un répertoire git spécifique, y compris un répertoire renommé / désactivé :
python3 scripts/git_repo_doctor.py --git-dir /path/to/.git.disabled-xyz

# Sortie exploitable par machine (à analyser en tant qu'agent) :
python3 scripts/git_repo_doctor.py --json

# Ignorer la sonde de joignabilité distante (hors ligne ou réseau lent) :
python3 scripts/git_repo_doctor.py --no-remote

Ce qu'il retourne

1. Répartition de la taille - déchets définitifs / objets en vrac / packs / historique atteignable / estimation des inatteignables / marge disque.
2. Problèmes de santé - gc.auto=0, gc.log obsolète, arbre de travail égal à $HOME, Syncthing synchronisant .git, inondation d'objets en vrac, fichiers temporaires oubliés.
3. Une recommandation, parmi :
   • VOIE A (historique atteignable minuscule) : archive de sécurité, prouver qu'elle restaure, puis suppression différée par couches.
   • VOIE B (historique substantiel) : git maintenance + gc/repack sur place ; si le disque est juste, supprimer d'abord les déchets.
   • Indice filter-repo / BFG lorsque des blocs énormes vivent dans l'historique atteignable.
4. Un plan de nettoyage prêt à coller, avec rollback, comprenant des points de restauration explicites. Le script imprime les commandes et n'en exécute aucune.

Comment l'agent doit utiliser la sortie

• Exécuter le script, puis résumer la répartition de la taille, les problèmes de santé et la VOIE recommandée pour l'utilisateur.
• Présenter le plan imprimé mais NE PAS exécuter de commande automatiquement. Le nettoyage est irréversible ; l'humain doit confirmer chaque étape destructive.
• Toujours vérifier la valeur de $GITDIR, s'assurer que l'archive est créée et vérifiée, et conserver l'archive jusqu'à ce que l'utilisateur soit sûr.

Contrat de sécurité

Cet outil n'exécute jamais gc, prune, repack, rm, reflog expire, ni aucune commande mutante. Les seules choses qu'il exécute sont des requêtes git en lecture seule et des statistiques du système de fichiers, toutes protégées par un délai d'attente. Chaque action destructive n'existe que sous forme de texte dans le plan imprimé, pour qu'un humain le révise et l'exécute.

Logique de décision (résumé)

Condition	Recommandation
atteignable < 1 Gio et < 10 % du total	VOIE A : archive + suppression/ reconstruction par couches
atteignable substantiel, espace disponible ample	VOIE B : git maintenance + gc/repack sur place
atteignable substantiel, disque juste	supprimer d'abord les déchets, puis repaqueter
peu d'objets paquetés mais taille de pack énorme	indice de bloc géant (lancer git-sizer, envisager git-filter-repo)

Voir README.md pour la documentation complète et un exemple de rapport.