git-annex/ tips/ what to do when a repository is corrupted

A git-annex repository on a removable USB drive is great, until the cable falls out at the wrong time and git's repository gets trashed. The way git checksums everything and the poor quality of USB media makes this perhaps more likely than you would expect. If this happens to you, here's a way to recover that makes the most of whatever data is left on the drive.

- First, run `git fsck`. If it does not report any problems, your data is fine, and you don't need to proceed further.
- So `git fsck` says the git repository is corrupted. But probably the data git-annex stored is fine. Your first step is to clone another copy of the git repository from somewhere else. Let's call this clone "$good", and the corrupted repository "$bad".
- Preserve your git configuration changes, and the `annex.uuid` setting: `mv $bad/.git/config $good/.git/config`
- Move annexed data into the new repository: `mkdir $good/.git/annex; mv $bad/.git/annex/objects $good/.git/annex/objects`
- Reinitalize git-annex: `cd $good; git annex init`
- Check for any problems with the annexed data: `cd $good; git annex fsck`
- Now you can remove the corrupted repository, the new one is ready to use.

Alternatively, recent versions of git-annex have a `git annex repair` command that uses http://git-repair.branchable.com/ to repair a repository in-place. The git-annex assistant will detect most corruptions and offer to run the repair for you automatically.

--Joey

comment 6
@sng you can clone any git repository, it does not need to be a bare one.
Comment by joey — Tue Jul 22 18:11:47 2025
corrupted bare repo
I've tried following these steps with a bare repo that became corrupted somehow, but at the cloning another repo step I'm stuck... how do I clone a repo when the bare repo is the one corrupted? (if it matters, this is a very large repo of photo files)
Comment by sng — Tue Jul 22 18:11:47 2025
Thanks!
This worked like a charm.
Comment by bjornw — Tue Jul 22 18:11:47 2025
comment 3
@Maarten git clone from one of the other clones of the repository to the new drive. Also, recent versions of git-annex have a `git annex reinit` command that can be used to easily initialize a repository with the same settings as a repository that was lost.
Comment by http://joeyh.name/ — Tue Jul 22 18:11:47 2025
comment 2
What if the drive is destroyed? How would I re-initialize a new drive to act as a substitute for the remote that was just lost?
Comment by https://www.google.com/accounts/o8/id?id=AItOawmZilYULa6CDEGfuagoDlesyakBgnf-dF8 — Tue Jul 22 18:11:47 2025
Automation
Could this step be automated?
Comment by https://www.google.com/accounts/o8/id?id=AItOawnq-RfkVpFN15SWvQ2lpSGAi0XpNQuLxKM — Tue Jul 22 18:11:47 2025
Comments on this page are closed.