git-repo-doctor 是做什麼的？
唯讀診斷與安全清理顧問，專為臃腫的 Git 倉庫設計。
何時使用此技能
.git目錄膨脹至數 GB。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
回傳內容
- 大小明細 – 明確垃圾 / 鬆散物件 / pack 檔案 / 可達歷史 / 不可達預估 / 磁碟空間裕量。
- 健康問題 –
gc.auto=0、過期的gc.log、工作目錄等於$HOME、Syncthing 同步.git、鬆散物件氾濫、殘留暫存檔案。 - 建議方案，為以下之一：
- 路徑 A（可達歷史極小）：製作安全性網包，證明其可還原，然後分層延遲刪除。
- 路徑 B（歷史龐大）：原地執行
git maintenance+gc/repack；若磁碟空間不足，先刪除垃圾再 repack。 - filter-repo / BFG 提示：當可達歷史中有巨大 blob 時。
- 可供貼上、具回滾意識的清理計劃，附帶明確的回滾點。腳本會輸出指令但不會執行任何指令。
代理應如何使用輸出
- 執行腳本，然後向使用者摘要說明大小明細、健康問題以及建議的路徑。
- 呈現輸出的計劃，但不要自動執行其中的任何指令。清理是不可逆的；使用者必須確認每個破壞性步驟。
- 始終確認
$GITDIR的值，確保已建立並驗證安全性網包，並在使用者確定之前保留該網包。
安全合約
此工具絕對不會執行 gc、prune、repack、rm、reflog expire 或任何變更指令。它唯一執行的是唯讀的 git 查詢和檔案系統統計，且全部設有超時保護。每個破壞性動作僅以文字形式存在於輸出的計劃中，供人類審閱和執行。
決策邏輯（摘要）
| 條件 | 建議 |
|---|---|
| 可達歷史 < 1 GiB 且小於總量的 10% | 路徑 A：製作網包 + 分層刪除 / 重建 |
| 可達歷史龐大且剩餘空間充足 | 路徑 B：原地執行 git maintenance + gc/repack |
| 可達歷史龐大但磁碟空間緊缺 | 先刪除垃圾，再 repack |
| pack 物件少但 pack 檔案極大 | 巨大 blob 提示（執行 git-sizer，考慮 git-filter-repo） |
完整文件與範例報告請參閱 README.md。