| name | recover-a-corrupted-git-repository |
| category | code |
| description | Recover a corrupted Git repository through preservation, object and reference diagnosis, alternate-copy inventory, minimal repair, and independent verification. Use when objects, refs, index, worktree, or repository metadata are damaged. |
recover-a-corrupted-git-repository
Preserve every unique object and uncommitted file before repair.
When to use
- Use for checksum errors, missing objects, invalid refs, broken index, failed fetch, or inaccessible history.
- Do not run destructive cleanup, reset, checkout, or garbage collection before preservation.
Preconditions
- Record symptoms, repository path, filesystem state, remotes, clones, worktrees, bundles, backups, reflogs, and uncommitted work.
Procedure
- Stop automated fetch, maintenance, cleanup, and writes.
- Copy repository metadata and worktree through an authorized recoverable method.
- Inventory refs, reflogs, alternates, worktrees, submodules, remotes, packs, loose objects, and unique files.
- Run read-only integrity checks and classify index, ref, object, pack, config, or filesystem damage.
- Obtain missing objects only from verified clones, remotes, bundles, backups, or collaborators.
- Repair the smallest affected layer and preserve conflicting evidence.
- Rebuild derived index or metadata only after unique state is safe.
- Verify history, trees, tags, signatures, worktrees, builds, and remote comparison before resuming.
Failure plan
- If unique objects remain missing, preserve partial history and document the exact loss rather than fabricating continuity.
Worked example
A missing pack exists in a verified colleague bundle; recovery imports it into a copy, rebuilds the index, and preserves three uncommitted files.
Done
- A repository recovery report records preserved copies, integrity findings, sources, repairs, remaining loss, and resumed state
- Object, ref, reflog, worktree, signature, build, remote, uncommitted-file, and independent-copy checks verify recovery
