git-repo-doctor은(는) 무엇을 하나요?
비대한 Git 저장소를 위한 읽기 전용 진단 및 안전 정리 조언 도구입니다.
이 스킬을 사용해야 하는 경우
.git디렉토리가 수 기가바이트까지 커졌을 때objects/pack/tmp_pack_*또는objects/??/tmp_obj_*파일이 계속 쌓일 때git count-objects -v에서garbage수치가 크거나 수십만 개의 느슨한 객체가 표시될 때gc.auto=0이 설정되었거나, gc/repack/fetch가 계속 중단될 때- 편집기나 코딩 에이전트(Codex, Claude Code, Cursor, IDE 인덱서)가 저장소를 스캔하다가 크래시나 OOM이 발생할 때
- 사용자가 안전하게 저장소를 축소, 정리, 프루닝, 가비지 컬렉션하거나 디스크 공간을 회수하는 방법을 물어볼 때
실행 방법
의존성이 없는 단일 Python 3 스크립트입니다. 엄격히 읽기 전용입니다.
# 현재 디렉토리가 포함된 저장소 진단:
python3 scripts/git_repo_doctor.py
# 특정 Git 디렉토리(이름이 바뀌거나 비활성화된 것 포함) 지정:
python3 scripts/git_repo_doctor.py --git-dir /path/to/.git.disabled-xyz
# 기계가 읽기 쉬운 출력(에이전트로 동작 시 파싱 용도):
python3 scripts/git_repo_doctor.py --json
# 원격 저장소 도달 가능성 검사 건너뛰기(오프라인 또는 느린 네트워크):
python3 scripts/git_repo_doctor.py --no-remote
반환 내용
- 크기 분석 - 명확한 가비지 / 느슨한 객체 / 팩 파일 / 도달 가능한 히스토리 / 도달 불가능 추정치 / 디스크 여유 공간
- 건강 문제 -
gc.auto=0, 오래된gc.log, 작업 트리가$HOME과 동일, Syncthing이.git동기화, 느슨한 객체 홍수, 남은 임시 파일 - 권장 사항 (다음 중 하나):
- PATH A (도달 가능한 히스토리가 작은 경우): 번들 안전망 생성, 복원 증명 후 계층적 지연 삭제
- PATH B (히스토리가 큰 경우): 현재 위치에서
git maintenance+gc/repack수행; 디스크가 부족하면 먼저 가비지 삭제 - filter-repo / BFG 힌트: 도달 가능한 히스토리에 거대 blob이 있는 경우
- 복사하여 사용할 수 있는 롤백 가능 정리 계획 - 명시적인 롤백 지점 포함. 스크립트는 명령어를 출력만 하고 실행하지 않습니다.
에이전트가 출력을 사용하는 방법
- 스크립트를 실행한 후 크기 분석, 건강 문제, 권장 PATH를 사용자에게 요약하여 알려줍니다.
- 출력된 계획을 제시하지만, 어떤 명령도 자동으로 실행하지 마십시오. 정리는 되돌릴 수 없으며, 사람이 각 파괴적 단계를 확인해야 합니다.
- 항상
$GITDIR값을 확인하고, 번들이 생성되고 검증되었는지 확인하며, 사용자가 확신할 때까지 번들을 유지하세요.
안전 계약
이 도구는 gc, prune, repack, rm, reflog expire 또는 어떤 변경 명령도 실행하지 않습니다. 실행하는 것은 읽기 전용 git 쿼리와 파일 시스템 통계뿐이며, 모두 타임아웃으로 보호됩니다. 모든 파괴적 동작은 사람이 검토하고 실행할 수 있도록 출력된 계획의 텍스트로만 존재합니다.
결정 로직 (요약)
| 조건 | 권장 사항 |
|---|---|
| 도달 가능 < 1 GiB 및 전체의 10% 미만 | PATH A: 번들 + 계층적 삭제/재구축 |
| 도달 가능이 크고 여유 공간 충분 | PATH B: git maintenance + 현재 위치에서 gc/repack |
| 도달 가능이 크고 디스크 부족 | 먼저 가비지 삭제 후 repack |
| 팩 객체 수는 적지만 팩 크기가 큼 | 거대 blob 힌트 (git-sizer 실행, git-filter-repo 고려) |
전체 문서 및 예제 보고서는 README.md를 참조하세요.