LaughingisLaughing/git-repo-doctor

O que git-repo-doctor faz?

Diagnóstico somente leitura e consultor de limpeza segura para repositórios Git inchados.

Quando usar esta skill

• O diretório .git cresceu para muitos gigabytes.
• Arquivos objects/pack/tmp_pack_* ou objects/??/tmp_obj_* estão se acumulando.
• git count-objects -v mostra uma grande contagem de garbage ou centenas de milhares de objetos soltos.
• gc.auto=0, ou gc / repack / fetch é constantemente interrompido.
• Um editor ou agente de codificação (Codex, Claude Code, Cursor, um indexador de IDE) trava ou fica sem memória ao escanear um repositório.
• O usuário pergunta como encolher, limpar, podar, coletar lixo ou recuperar espaço com segurança de um repositório.

Como executar

Único script Python 3 sem dependências. Ele é estritamente SOMENTE LEITURA.

# Diagnosticar o repositório que contém o diretório atual:
python3 scripts/git_repo_doctor.py

# Apontar para um diretório git específico, incluindo um renomeado / desabilitado:
python3 scripts/git_repo_doctor.py --git-dir /path/to/.git.disabled-xyz

# Saída legível por máquina (analise isso ao atuar como um agente):
python3 scripts/git_repo_doctor.py --json

# Pular a sonda de acessibilidade remota (rede offline ou lenta):
python3 scripts/git_repo_doctor.py --no-remote

O que retorna

1. Detalhamento de tamanho - lixo definitivo / solto / packs / histórico acessível / estimativa inacessível / espaço livre do disco.
2. Problemas de saúde - gc.auto=0, gc.log obsoleto, worktree igual a $HOME, Syncthing sincronizando .git, enxurrada de objetos soltos, arquivos temporários restantes.
3. Uma recomendação uma das:
   • CAMINHO A (histórico acessível pequeno): criar um bundle como rede de segurança, provar que restaura, depois uma exclusão em camadas com atraso.
   • CAMINHO B (histórico substancial): uso de git maintenance + gc/repack no local; se o disco estiver cheio, exclua lixo primeiro.
   • Dica de filter-repo / BFG quando blobs gigantes estão no histórico acessível.
4. Um plano de limpeza com rollback, pronto para copiar e colar com pontos de rollback explícitos. O script imprime os comandos e não executa nenhum deles.

Como o agente deve usar a saída

• Execute o script, depois resuma o detalhamento de tamanho, os problemas de saúde e o CAMINHO recomendado para o usuário.
• Apresente o plano impresso, mas NÃO execute nenhum comando dele automaticamente. A limpeza é irreversível; o humano deve confirmar cada passo destrutivo.
• Sempre confirme o valor de $GITDIR, assegure-se de que o bundle foi criado e verificado, e mantenha o bundle até que o usuário tenha certeza.

Contrato de segurança

Esta ferramenta nunca executa gc, prune, repack, rm, reflog expire ou qualquer comando mutante. As únicas coisas que ela executa são consultas git somente leitura e estatísticas de sistema de arquivos, todas com proteção de tempo limite. Cada ação destrutiva existe exclusivamente como texto no plano impresso para que um humano revise e execute.

Lógica de decisão (resumo)

Condição	Recomendação
Acessível < 1 GiB e < 10% do total	CAMINHO A: bundle + exclusão / reconstrução em camadas
Acessível substancial, espaço livre amplo	CAMINHO B: git maintenance + gc/repack no local
Acessível substancial, disco cheio	Excluir lixo primeiro, depois repack
Poucos objetos empacotados, mas tamanho do pack enorme	Dica de blob gigante (execute git-sizer, considere git-filter-repo)

Veja README.md para documentação completa e um relatório de exemplo.