git-annex/ git-annex-repair

# NAME

git-annex repair - recover broken git repository

# SYNOPSIS

git annex repair

# DESCRIPTION

This can repair many of the problems with git repositories that `git fsck` detects, but does not itself fix. It's useful if a repository has become badly damaged. One way this can happen is if a repository used by git-annex is on a removable drive that gets unplugged at the wrong time.

This command can actually be used inside git repositories that do not use git-annex at all; when used in a repository using git-annex, it does additional repairs of the git-annex branch.

It works by deleting any corrupt objects from the git repository, and retrieving all missing objects it can from the remotes of the repository.

If that is not sufficient to fully recover the repository, it can also reset branches back to commits before the corruption happened, delete branches that are no longer available due to the lost data, and remove any missing files from the index. It will only do this if run with the `--force` option, since that rewrites history and throws out missing data. Note that the `--force` option never touches tags, even if they are no longer usable due to missing data.

After running this command, you will probably want to run `git fsck` to verify it fixed the repository. Note that fsck may still complain about objects referenced by the reflog, or the stash, if they were unable to be recovered. This command does not try to clean up either the reflog or the stash.

It is also a good idea to run `git annex fsck --fast` after this command, to make sure that the git-annex branch reflects reality.

# OPTIONS

- `--force`

  Enable repair actions that involve deleting data that has been lost due to git repository corruption.

- Also the git-annex-common-options(1) can be used.

# SEE ALSO

git-annex(1)

git-annex-fsck(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

When a weird 'no space left on device' error appears

When you run into weird `no space left on device` errors although there clearly is enough room on your disk while running `git annex repair`, it probably means that your `/tmp` is too small (You can verify with `watch -n0 df -h` or just `df -h`). You can instruct `git annex repair` to use a different directory for intermediate storage via the `TMPDIR` environment variable:

    mkdir /path/to/dir/with/enough/space
    TMPDIR=/path/to/dir/with/enough/space git annex repair
    # Now that new dir is used and the 'no space left on device' error should disappear

Might be worth adding a note for `TMPDIR` to the `git annex repair` manpage, @joey?

Comment by nobodyinperson — Tue Jul 22 18:11:47 2025
Comments on this page are closed.